conf.py
7.66 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
# sys.path.insert(0, os.path.abspath('.'))
#import pathlib
#sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())
# - for code style examples :
sys.path.insert(0, os.path.abspath('../../../doc'))
# - for PyROS :
sys.path.insert(0, os.path.abspath('../../..'))
sys.path.insert(0, os.path.abspath('../../../src'))
sys.path.insert(0, os.path.abspath('../../../src/core'))
# - for guitastro :
sys.path.insert(0, os.path.abspath('../../../vendor'))
#sys.path.insert(0, os.path.abspath('../../../src/device_controller'))
#sys.path.insert(0, os.path.abspath('../../../src/core/pyros_django'))
#sys.path.insert(0, os.path.abspath('../../../src/core/celme'))
sys.setrecursionlimit(1500)
# -- Project information -----------------------------------------------------
project = 'PyROS'
copyright = '2022, E. Pallier, A. Klotz, A. Koralewski'
author = 'E. Pallier, A. Klotz, A. Koralewski'
# The full version, including alpha/beta/rc tags
release = '0.4.1'
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc', # automatically generate documentation for modules
#'sphinx.ext.autosectionlabel', # automatic link to chapters
# (EP) sphinx-autodoc-typehints
# https://pypi.org/project/sphinx-autodoc-typehints
# TODO: pip install sphinx-autodoc-typehints
# TODO: make sure you load sphinx.ext.napoleon first, before sphinx-autodoc-typehints
'sphinx.ext.napoleon', # to read Google-style or Numpy-style docstrings
'sphinx_autodoc_typehints',
'sphinx.ext.todo',
#'sphinx.ext.duration',
'sphinx.ext.doctest',
#'sphinx.ext.autosummary',
"autodocsumm", # to generate tables of functions, attributes, methods, etc. (python3 -m pip install autodocsumm)
'sphinx.ext.intersphinx',
'sphinx.ext.mathjax',
'sphinx.ext.viewcode', # to allow vieing the source code in the web page
'sphinx.ext.graphviz',
#'sphinx_pyreverse',
'rst2pdf.pdfbuilder',
# to be used with option : show-inheritance-diagram (mais ne marche pas pour l'instant...)
'sphinx.ext.inheritance_diagram',
]
'''
try:
extensions.append('sphinx_pyreverse')
except ModuleNotFoundError:
pass # pip install sphinx_pyreverse
try:
import rst2pdf
extensions.append('rst2pdf.pdfbuilder')
except ModuleNotFoundError:
pass # no rst2pdf for you
'''
# (EP) To avoid sorting of methods & attributes, very annoying... (so, keep them in samed order as in source)
#autodoc_member_order = 'bysource'
# (EP) Default config for autodoc
#'members': 'var1, var2',
#'special-members': '__init__, __str__',
#'special-members': '__str__',
#'autoclass_content': 'class',
#'exclude-members': '__init__, __weakref__',
autodoc_default_options = {
# make autodocsumm active by default for all autodoc directives
'autosummary': True,
# autodoc will also generate document for the undoc-umented members (not having docstrings)
'undoc-members': True,
'member-order': 'bysource',
'special-members': '__str__',
#'special-members': '__init__, __str__',
#'exclude-members': '__weakref__',
'show-inheritance': True,
#'show-inheritance': False,
# ne marche pas ?
'show-inheritance-diagram': True,
'typehints_fully_qualified': False,
# (EP) nothing below is taken into account...
##'add_module_names': False,
##'autoclass_content': 'init',
#'autoclass_content': 'both',
#'autodoc_typehints': 'signature',
##'autodoc_typehints': 'both',
#'autodoc_typehints': 'description',
##'autodoc_typehints_description_target': 'all',
#'autodoc_class_signature': 'mixed',
#'autodoc_class_signature': 'separated',
}
#print(autodoc_default_options)
#exit
# (EP) necessary because not taken into account in autodoc_default_options above !!!!!!
# - short module name
add_module_names = False
# Le commentaire de la methode __init__ est rajouté au commentaire de la classe ?
# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autoclass_content
# - NON
#autoclass_content = 'class'
# - OUI
#autoclass_content = 'init'
# - OUI, les 2 commentaires (class et init) sont fusionnés
autoclass_content = 'both'
# - Documenter automatiquement TOUS les arguments de methodes, meme ceux qui ne sont pas explicitement documentés
#autodoc_typehints = 'both'
#autodoc_typehints = 'signature'
# Show types only in descriptions, not in signatures
autodoc_typehints = "description"
# don't include docstrings from the parent class
autodoc_inherit_docstrings = False
# This value controls whether the types of undocumented parameters and return values are documented when autodoc_typehints is set to description.
# The default value is "all", meaning that types are documented for all parameters and return values, whether they are documented or not.
# When set to "documented", types will only be documented for a parameter or a return value that is already documented by the docstring.
##autodoc_typehints_description_target = 'all'
# Afficher le nom de la classe AVEC ses arguments ou SANS ?
# - AVEC
autodoc_class_signature = 'mixed'
# - SANS
#autodoc_class_signature = 'separated'
# Napoleon settings
# https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#configuration
napoleon_google_docstring = True
napoleon_numpy_docstring = False
#napoleon_include_init_with_doc = False
'''
napoleon_include_private_with_doc = False
napoleon_include_special_with_doc = True
napoleon_use_admonition_for_examples = False
napoleon_use_admonition_for_notes = False
napoleon_use_admonition_for_references = False
napoleon_use_ivar = False
napoleon_use_param = True
napoleon_use_rtype = True
napoleon_preprocess_types = False
napoleon_type_aliases = None
napoleon_attr_annotations = True
'''
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
#exclude_patterns = []
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
#html_theme = 'alabaster'
# (EP) Read The Docs theme
html_theme = 'sphinx_rtd_theme'
# Set html_theme to default for “standard” ReadTheDocs theme
#html_theme = 'default'
#html_theme = 'nature'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
autosummary_generate = True
# Added to avoid this error :
# [ERROR] createpdf.py:1134 Template 'twoColumn' is not defined
# => twoColumn is no longer part of the default styles in rst2pdf 0.99, so you now need to explicitly include the twoColumn style file.
pdf_stylesheets = ['twocolumn']