Skip to content

Commit 9f8d2a4

Browse files
rabbitixrabbitix
committed
[Fix] Change the doce config
1 parent 41771e4 commit 9f8d2a4

3 files changed

Lines changed: 123 additions & 44 deletions

File tree

‎.readthedocs.yaml‎

Lines changed: 33 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,51 @@
11
# .readthedocs.yaml
2-
# Read the Docs configuration file
2+
# Read the Docs configuration file optimized for thorough code extraction
33
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
44

55
version: 2
66

7+
# Set the OS and Python version
78
build:
89
os: ubuntu-22.04
910
tools:
10-
python: "3.13"
11+
python: "3.13" # Using a stable Python version supported by ReadTheDocs
1112
jobs:
13+
pre_build:
14+
# Generate API docs from source before building
15+
- cd docs && sphinx-apidoc -o source/ ../archipy -f -e -M -T
1216
post_create_environment:
13-
# Install poetry
17+
# Install poetry and configure it
1418
- pip install poetry
15-
# Tell poetry to not use a virtual environment
1619
- poetry config virtualenvs.create false
1720
post_install:
18-
# Install dependencies with poetry
19-
- poetry install --with docs
21+
# Ensure we have the latest documentation tools
22+
- pip install --upgrade sphinx sphinx-rtd-theme sphinx-autodoc-typehints sphinx-autoapi
2023

24+
# Use the latest version of build system
25+
python:
26+
install:
27+
- method: pip
28+
path: .
29+
extra_requirements:
30+
- docs
31+
- requirements: docs/requirements.txt
2132

33+
# Build documentation with maximum extraction settings
2234
sphinx:
2335
configuration: docs/source/conf.py
36+
fail_on_warning: true # Set to true once your docs are stable
37+
builder: html
2438

25-
python:
26-
install:
27-
- requirements: docs/requirements.txt
39+
# Additional formats for download
40+
formats:
41+
- pdf
42+
- epub
43+
44+
# Search settings
45+
search:
46+
ranking:
47+
# These paths will be ranked higher in search results
48+
api_reference/*: 2
49+
usage.rst: 3
50+
installation.rst: 3
51+
architecture.rst: 2

‎docs/requirements.txt‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,12 @@
1-
sphinx==8.2.1
2-
sphinx-rtd-theme==3.0.2
3-
sphinx-autodoc-typehints==3.1.0
1+
sphinx>=6.0.0
2+
sphinx-rtd-theme>=1.2.0
3+
sphinx-autodoc-typehints>=1.24.0
4+
sphinx-autoapi>=2.1.0
5+
sphinxcontrib-applehelp>=1.0.4
6+
sphinxcontrib-devhelp>=1.0.2
7+
sphinxcontrib-htmlhelp>=2.0.1
8+
sphinxcontrib-jsmath>=1.0.1
9+
sphinxcontrib-qthelp>=1.0.3
10+
sphinxcontrib-serializinghtml>=1.1.5
11+
autodocsumm>=0.2.10
12+
myst-parser>=1.0.0

‎docs/source/conf.py‎

Lines changed: 78 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -5,43 +5,88 @@
55

66
import os
77
import sys
8-
9-
sys.path.insert(0, os.path.abspath("../.."))
8+
sys.path.insert(0, os.path.abspath('../..'))
109

1110
# -- Project information -----------------------------------------------------
1211
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
1312

14-
project = "ArchiPy"
15-
copyright = "2024, Mehdi Einali, Hossein Nejati"
16-
author = "Mehdi Einali, Hossein Nejati"
17-
version = "0.1.0"
18-
release = "0.1.0"
13+
project = 'ArchiPy'
14+
copyright = '2024, Mehdi Einali, Hossein Nejati'
15+
author = 'Mehdi Einali, Hossein Nejati'
16+
version = '0.1.0'
17+
release = '0.1.0'
1918

2019
# -- General configuration ---------------------------------------------------
2120
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
2221

2322
extensions = [
24-
"sphinx.ext.autodoc",
25-
"sphinx.ext.viewcode",
26-
"sphinx.ext.napoleon",
27-
"sphinx_autodoc_typehints",
28-
"sphinx.ext.intersphinx",
29-
"sphinx.ext.autosectionlabel",
23+
'sphinx.ext.autodoc',
24+
'sphinx.ext.viewcode',
25+
'sphinx.ext.napoleon',
26+
'sphinx_autodoc_typehints',
27+
'sphinx.ext.intersphinx',
28+
'sphinx.ext.autosectionlabel',
29+
'sphinx.ext.coverage',
30+
'sphinx.ext.inheritance_diagram',
31+
'sphinx.ext.todo',
32+
'sphinx.ext.autosummary',
33+
'autoapi.extension',
34+
'autodocsumm',
35+
]
36+
37+
# AutoAPI settings for better code extraction
38+
autoapi_type = 'python'
39+
autoapi_dirs = ['../../archipy']
40+
autoapi_options = [
41+
'members',
42+
'undoc-members',
43+
'private-members',
44+
'special-members',
45+
'inherited-members',
46+
'show-inheritance',
47+
'show-module-summary',
48+
'imported-members',
3049
]
50+
autoapi_python_class_content = 'both'
51+
autoapi_member_order = 'groupwise'
52+
autoapi_add_toctree_entry = False # We'll handle this in our own index
3153

32-
templates_path = ["_templates"]
54+
templates_path = ['_templates']
3355
exclude_patterns = []
3456

3557
# -- Options for autodoc -----------------------------------------------------
36-
autodoc_member_order = "bysource"
37-
autodoc_typehints = "description"
38-
autoclass_content = "both"
58+
autodoc_member_order = 'bysource'
59+
autodoc_typehints = 'description'
60+
autoclass_content = 'both'
3961
autodoc_default_options = {
40-
"members": True,
41-
"show-inheritance": True,
42-
"undoc-members": True,
62+
'members': True,
63+
'member-order': 'bysource',
64+
'special-members': True,
65+
'inherited-members': True,
66+
'show-inheritance': True,
67+
'undoc-members': True,
68+
'private-members': True, # Include private members with leading underscore
69+
'ignore-module-all': True,
4370
}
4471

72+
# Enable auto-summary generation
73+
autosummary_generate = True
74+
75+
# Include __init__ method docstring in class docstring
76+
autoclass_content = 'both'
77+
78+
# Enable todos
79+
todo_include_todos = True
80+
81+
# Inheritance diagrams
82+
inheritance_graph_attrs = dict(rankdir="TB", size='"12.0, 12.0"', fontsize=14, ratio='compress')
83+
inheritance_node_attrs = dict(shape='rect', fontsize=14, height=0.75, margin='"0.08, 0.05"')
84+
85+
# Enable documenting typehints
86+
autodoc_typehints = 'description'
87+
typehints_fully_qualified = False
88+
always_document_param_types = True
89+
4590
# -- Options for napoleon ----------------------------------------------------
4691
napoleon_google_docstring = True
4792
napoleon_numpy_docstring = False
@@ -60,18 +105,18 @@
60105
# -- Options for HTML output -------------------------------------------------
61106
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
62107

63-
html_theme = "sphinx_rtd_theme"
64-
html_static_path = ["_static"]
108+
html_theme = 'sphinx_rtd_theme'
109+
html_static_path = ['_static']
65110
html_logo = None
66111
html_favicon = None
67112
html_title = f"{project} {version} Documentation"
68113
html_short_title = project
69114

70115
# -- Options for intersphinx -------------------------------------------------
71116
intersphinx_mapping = {
72-
"python": ("https://docs.python.org/3", None),
73-
"sqlalchemy": ("https://docs.sqlalchemy.org/en/14/", None),
74-
"pydantic": ("https://docs.pydantic.dev/", None),
117+
'python': ('https://docs.python.org/3', None),
118+
'sqlalchemy': ('https://docs.sqlalchemy.org/en/14/', None),
119+
'pydantic': ('https://docs.pydantic.dev/', None),
75120
}
76121

77122
# -- Options for autosectionlabel --------------------------------------------
@@ -82,15 +127,16 @@
82127

83128
# -- Options for LaTeX output ------------------------------------------------
84129
latex_elements = {
85-
"papersize": "a4paper",
86-
"pointsize": "11pt",
87-
"preamble": "",
88-
"figure_align": "htbp",
130+
'papersize': 'a4paper',
131+
'pointsize': '11pt',
132+
'preamble': '',
133+
'figure_align': 'htbp',
89134
}
90135

91136
# Define master_doc (the main document)
92-
master_doc = "index"
137+
master_doc = 'index'
93138

94139
latex_documents = [
95-
(master_doc, "ArchiPy.tex", "ArchiPy Documentation", author, "manual"),
96-
]
140+
(master_doc, 'ArchiPy.tex', 'ArchiPy Documentation',
141+
author, 'manual'),
142+
]

0 commit comments

Comments
 (0)