Commit 8dde94f8f3f3351e9a6467268a02251214a325ca
1 parent
78557f8c
Exists in
dev
début de la doc rst.
Showing
5 changed files
with
526 additions
and
0 deletions
Show diff stats
@@ -0,0 +1,375 @@ | @@ -0,0 +1,375 @@ | ||
1 | +# pyros documentation build configuration file, created by | ||
2 | +# sphinx-quickstart on Sun Jun 26 00:00:43 2016. | ||
3 | +# | ||
4 | +# This file is execfile()d with the current directory set to its | ||
5 | +# containing dir. | ||
6 | +# | ||
7 | +# Note that not all possible configuration values are present in this | ||
8 | +# autogenerated file. | ||
9 | +# | ||
10 | +# All configuration values have a default; values that are commented out | ||
11 | +# serve to show the default. | ||
12 | + | ||
13 | +# If extensions (or modules to document with autodoc) are in another directory, | ||
14 | +# add these directories to sys.path here. If the directory is relative to the | ||
15 | +# documentation root, use os.path.abspath to make it absolute, like shown here. | ||
16 | +# | ||
17 | +# import os | ||
18 | +# import sys | ||
19 | +# sys.path.insert(0, os.path.abspath('.')) | ||
20 | + | ||
21 | +# -- General configuration ------------------------------------------------ | ||
22 | + | ||
23 | +# If your documentation needs a minimal Sphinx version, state it here. | ||
24 | +# | ||
25 | +# needs_sphinx = '1.0' | ||
26 | + | ||
27 | +# Add any Sphinx extension module names here, as strings. They can be | ||
28 | +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom | ||
29 | +# ones. | ||
30 | +extensions = [] | ||
31 | + | ||
32 | +# Add any paths that contain templates here, relative to this directory. | ||
33 | +templates_path = ['_templates'] | ||
34 | + | ||
35 | +# The suffix(es) of source filenames. | ||
36 | +# You can specify multiple suffix as a list of string: | ||
37 | +# | ||
38 | +# source_suffix = ['.rst', '.md'] | ||
39 | +source_suffix = '.rst' | ||
40 | + | ||
41 | +# The encoding of source files. | ||
42 | +# | ||
43 | +# source_encoding = 'utf-8-sig' | ||
44 | + | ||
45 | +# The master toctree document. | ||
46 | +master_doc = 'index' | ||
47 | + | ||
48 | +# General information about the project. | ||
49 | +project = u'Python Robotic Observatory Software' | ||
50 | +copyright = u'2021, IRAP' | ||
51 | +author = u'E. Pallier, A. Koralewski, A. Klotz' | ||
52 | + | ||
53 | +# The version info for the project you're documenting, acts as replacement for | ||
54 | +# |version| and |release|, also used in various other places throughout the | ||
55 | +# built documents. | ||
56 | +# | ||
57 | +# The short X.Y version. | ||
58 | +version = u'1.0' | ||
59 | +# The full version, including alpha/beta/rc tags. | ||
60 | +release = u'1.0.0' | ||
61 | + | ||
62 | +# The language for content autogenerated by Sphinx. Refer to documentation | ||
63 | +# for a list of supported languages. | ||
64 | +# | ||
65 | +# This is also used if you do content translation via gettext catalogs. | ||
66 | +# Usually you set "language" from the command line for these cases. | ||
67 | +language = None | ||
68 | + | ||
69 | +# There are two options for replacing |today|: either, you set today to some | ||
70 | +# non-false value, then it is used: | ||
71 | +# | ||
72 | +# today = '' | ||
73 | +# | ||
74 | +# Else, today_fmt is used as the format for a strftime call. | ||
75 | +# | ||
76 | +# today_fmt = '%B %d, %Y' | ||
77 | + | ||
78 | +# List of patterns, relative to source directory, that match files and | ||
79 | +# directories to ignore when looking for source files. | ||
80 | +# These patterns also affect html_static_path and html_extra_path | ||
81 | +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] | ||
82 | + | ||
83 | +# The reST default role (used for this markup: `text`) to use for all | ||
84 | +# documents. | ||
85 | +# | ||
86 | +# default_role = None | ||
87 | + | ||
88 | +# If true, '()' will be appended to :func: etc. cross-reference text. | ||
89 | +# | ||
90 | +# add_function_parentheses = True | ||
91 | + | ||
92 | +# If true, the current module name will be prepended to all description | ||
93 | +# unit titles (such as .. function::). | ||
94 | +# | ||
95 | +# add_module_names = True | ||
96 | + | ||
97 | +# If true, sectionauthor and moduleauthor directives will be shown in the | ||
98 | +# output. They are ignored by default. | ||
99 | +# | ||
100 | +# show_authors = False | ||
101 | + | ||
102 | +# The name of the Pygments (syntax highlighting) style to use. | ||
103 | +pygments_style = 'sphinx' | ||
104 | + | ||
105 | +# A list of ignored prefixes for module index sorting. | ||
106 | +# modindex_common_prefix = [] | ||
107 | + | ||
108 | +# If true, keep warnings as "system message" paragraphs in the built documents. | ||
109 | +# keep_warnings = False | ||
110 | + | ||
111 | +# If true, `todo` and `todoList` produce output, else they produce nothing. | ||
112 | +todo_include_todos = False | ||
113 | + | ||
114 | + | ||
115 | +# -- Options for HTML output ---------------------------------------------- | ||
116 | + | ||
117 | +# The theme to use for HTML and HTML Help pages. See the documentation for | ||
118 | +# a list of builtin themes. | ||
119 | +# | ||
120 | +html_theme = 'alabaster' | ||
121 | + | ||
122 | +# Theme options are theme-specific and customize the look and feel of a theme | ||
123 | +# further. For a list of options available for each theme, see the | ||
124 | +# documentation. | ||
125 | +# | ||
126 | +# html_theme_options = {} | ||
127 | + | ||
128 | +# Add any paths that contain custom themes here, relative to this directory. | ||
129 | +# html_theme_path = [] | ||
130 | + | ||
131 | +# The name for this set of Sphinx documents. | ||
132 | +# "<project> v<release> documentation" by default. | ||
133 | +# | ||
134 | +# html_title = u'pyros vpyros' | ||
135 | + | ||
136 | +# A shorter title for the navigation bar. Default is the same as html_title. | ||
137 | +# | ||
138 | +# html_short_title = None | ||
139 | + | ||
140 | +# The name of an image file (relative to this directory) to place at the top | ||
141 | +# of the sidebar. | ||
142 | +# | ||
143 | +# html_logo = None | ||
144 | + | ||
145 | +# The name of an image file (relative to this directory) to use as a favicon of | ||
146 | +# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 | ||
147 | +# pixels large. | ||
148 | +# | ||
149 | +# html_favicon = None | ||
150 | + | ||
151 | +# Add any paths that contain custom static files (such as style sheets) here, | ||
152 | +# relative to this directory. They are copied after the builtin static files, | ||
153 | +# so a file named "default.css" will overwrite the builtin "default.css". | ||
154 | +# html_static_path = ['_static'] | ||
155 | + | ||
156 | +# Add any extra paths that contain custom files (such as robots.txt or | ||
157 | +# .htaccess) here, relative to this directory. These files are copied | ||
158 | +# directly to the root of the documentation. | ||
159 | +# | ||
160 | +# html_extra_path = [] | ||
161 | + | ||
162 | +# If not None, a 'Last updated on:' timestamp is inserted at every page | ||
163 | +# bottom, using the given strftime format. | ||
164 | +# The empty string is equivalent to '%b %d, %Y'. | ||
165 | +# | ||
166 | +# html_last_updated_fmt = None | ||
167 | + | ||
168 | +# Custom sidebar templates, maps document names to template names. | ||
169 | +# | ||
170 | +# html_sidebars = {} | ||
171 | + | ||
172 | +# Additional templates that should be rendered to pages, maps page names to | ||
173 | +# template names. | ||
174 | +# | ||
175 | +# html_additional_pages = {} | ||
176 | + | ||
177 | +# If false, no module index is generated. | ||
178 | +# | ||
179 | +# html_domain_indices = True | ||
180 | + | ||
181 | +# If false, no index is generated. | ||
182 | +# | ||
183 | +# html_use_index = True | ||
184 | + | ||
185 | +# If true, the index is split into individual pages for each letter. | ||
186 | +# | ||
187 | +# html_split_index = False | ||
188 | + | ||
189 | +# If true, links to the reST sources are added to the pages. | ||
190 | +# | ||
191 | +# html_show_sourcelink = True | ||
192 | + | ||
193 | +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. | ||
194 | +# | ||
195 | +# html_show_sphinx = True | ||
196 | + | ||
197 | +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. | ||
198 | +# | ||
199 | +# html_show_copyright = True | ||
200 | + | ||
201 | +# If true, an OpenSearch description file will be output, and all pages will | ||
202 | +# contain a <link> tag referring to it. The value of this option must be the | ||
203 | +# base URL from which the finished HTML is served. | ||
204 | +# | ||
205 | +# html_use_opensearch = '' | ||
206 | + | ||
207 | +# This is the file name suffix for HTML files (e.g. ".xhtml"). | ||
208 | +# html_file_suffix = None | ||
209 | + | ||
210 | +# Language to be used for generating the HTML full-text search index. | ||
211 | +# Sphinx supports the following languages: | ||
212 | +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' | ||
213 | +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh' | ||
214 | +# | ||
215 | +# html_search_language = 'en' | ||
216 | + | ||
217 | +# A dictionary with options for the search language support, empty by default. | ||
218 | +# 'ja' uses this config value. | ||
219 | +# 'zh' user can custom change `jieba` dictionary path. | ||
220 | +# | ||
221 | +# html_search_options = {'type': 'default'} | ||
222 | + | ||
223 | +# The name of a javascript file (relative to the configuration directory) that | ||
224 | +# implements a search results scorer. If empty, the default will be used. | ||
225 | +# | ||
226 | +# html_search_scorer = 'scorer.js' | ||
227 | + | ||
228 | +# Output file base name for HTML help builder. | ||
229 | +htmlhelp_basename = 'pyros' | ||
230 | + | ||
231 | +# -- Options for LaTeX output --------------------------------------------- | ||
232 | + | ||
233 | +latex_elements = { | ||
234 | + # The paper size ('letterpaper' or 'a4paper'). | ||
235 | + # | ||
236 | + # 'papersize': 'letterpaper', | ||
237 | + | ||
238 | + # The font size ('10pt', '11pt' or '12pt'). | ||
239 | + # | ||
240 | + # 'pointsize': '10pt', | ||
241 | + | ||
242 | + # Additional stuff for the LaTeX preamble. | ||
243 | + # | ||
244 | + # 'preamble': '', | ||
245 | + | ||
246 | + # Latex figure (float) alignment | ||
247 | + # | ||
248 | + # 'figure_align': 'htbp', | ||
249 | +} | ||
250 | + | ||
251 | +# Grouping the document tree into LaTeX files. List of tuples | ||
252 | +# (source start file, target name, title, | ||
253 | +# author, documentclass [howto, manual, or own class]). | ||
254 | +latex_documents = [ | ||
255 | + (master_doc, 'pyros.tex', u'pyros Documentation', | ||
256 | + u'pyros', 'manual'), | ||
257 | +] | ||
258 | + | ||
259 | +# The name of an image file (relative to this directory) to place at the top of | ||
260 | +# the title page. | ||
261 | +# | ||
262 | +# latex_logo = None | ||
263 | + | ||
264 | +# If true, show page references after internal links. | ||
265 | +# | ||
266 | +# latex_show_pagerefs = False | ||
267 | + | ||
268 | +# If true, show URL addresses after external links. | ||
269 | +# | ||
270 | +# latex_show_urls = False | ||
271 | + | ||
272 | +# Documents to append as an appendix to all manuals. | ||
273 | +# | ||
274 | +# latex_appendices = [] | ||
275 | + | ||
276 | +# If false, no module index is generated. | ||
277 | +# | ||
278 | +# latex_domain_indices = True | ||
279 | + | ||
280 | + | ||
281 | +# -- Options for manual page output --------------------------------------- | ||
282 | + | ||
283 | +# One entry per manual page. List of tuples | ||
284 | +# (source start file, name, description, authors, manual section). | ||
285 | +man_pages = [ | ||
286 | + (master_doc, 'pyros', u'pyros Documentation', | ||
287 | + [author], 1) | ||
288 | +] | ||
289 | + | ||
290 | +# If true, show URL addresses after external links. | ||
291 | +# | ||
292 | +# man_show_urls = False | ||
293 | + | ||
294 | + | ||
295 | +# -- Options for Texinfo output ------------------------------------------- | ||
296 | + | ||
297 | +# Grouping the document tree into Texinfo files. List of tuples | ||
298 | +# (source start file, target name, title, author, | ||
299 | +# dir menu entry, description, category) | ||
300 | +texinfo_documents = [ | ||
301 | + (master_doc, 'pyros', u'pyros Documentation', | ||
302 | + author, 'pyros', 'One line description of project.', | ||
303 | + 'Miscellaneous'), | ||
304 | +] | ||
305 | + | ||
306 | +# Documents to append as an appendix to all manuals. | ||
307 | +# | ||
308 | +# texinfo_appendices = [] | ||
309 | + | ||
310 | +# If false, no module index is generated. | ||
311 | +# | ||
312 | +# texinfo_domain_indices = True | ||
313 | + | ||
314 | +# How to display URL addresses: 'footnote', 'no', or 'inline'. | ||
315 | +# | ||
316 | +# texinfo_show_urls = 'footnote' | ||
317 | + | ||
318 | +# If true, do not generate a @detailmenu in the "Top" node's menu. | ||
319 | +# | ||
320 | +# texinfo_no_detailmenu = False | ||
321 | + | ||
322 | +# -- A random example ----------------------------------------------------- | ||
323 | + | ||
324 | +import sys, os | ||
325 | +sys.path.insert(0, os.path.abspath('..')) | ||
326 | +# exclude_patterns = ['zzz'] | ||
327 | + | ||
328 | +numfig = True | ||
329 | +#language = 'ja' | ||
330 | + | ||
331 | +extensions.append('sphinx.ext.todo') | ||
332 | +extensions.append('sphinx.ext.autodoc') | ||
333 | +#extensions.append('sphinx.ext.autosummary') | ||
334 | +extensions.append('sphinx.ext.intersphinx') | ||
335 | +extensions.append('sphinx.ext.mathjax') | ||
336 | +extensions.append('sphinx.ext.viewcode') | ||
337 | +extensions.append('sphinx.ext.graphviz') | ||
338 | +try: | ||
339 | + extensions.append('sphinx_pyreverse') | ||
340 | +except ModuleNotFoundError: | ||
341 | + pass # pip install sphinx_pyreverse | ||
342 | + | ||
343 | +try: | ||
344 | + import rst2pdf | ||
345 | + extensions.append('rst2pdf.pdfbuilder') | ||
346 | +except ModuleNotFoundError: | ||
347 | + pass # no rst2pdf for you | ||
348 | + | ||
349 | +extensions.append('sphinx.ext.napoleon') | ||
350 | +# Napoleon settings | ||
351 | +napoleon_google_docstring = True | ||
352 | +napoleon_numpy_docstring = True | ||
353 | +napoleon_include_init_with_doc = False | ||
354 | +napoleon_include_private_with_doc = False | ||
355 | +napoleon_include_special_with_doc = True | ||
356 | +napoleon_use_admonition_for_examples = False | ||
357 | +napoleon_use_admonition_for_notes = False | ||
358 | +napoleon_use_admonition_for_references = False | ||
359 | +napoleon_use_ivar = False | ||
360 | +napoleon_use_param = True | ||
361 | +napoleon_use_rtype = True | ||
362 | +napoleon_type_aliases = None | ||
363 | +napoleon_attr_annotations = True | ||
364 | + | ||
365 | +pdf_documents = [ | ||
366 | + ('index', u'Python Robotic Observatory Software', u'Python Robotic Observatory Software', u'Etienne Pallier, Alexis Koralewski, Alain Klotz'), | ||
367 | +] | ||
368 | +# A comma-separated list of custom stylesheets. Example: | ||
369 | +pdf_stylesheets = ['sphinx', 'kerning', 'a4'] | ||
370 | + | ||
371 | + | ||
372 | +autosummary_generate = True | ||
373 | +html_theme = 'default' | ||
374 | +#html_theme = "nature" | ||
375 | +#source_suffix = ['.rst', '.txt'] | ||
0 | \ No newline at end of file | 376 | \ No newline at end of file |
@@ -0,0 +1,78 @@ | @@ -0,0 +1,78 @@ | ||
1 | +******************************************** | ||
2 | +Generate this documentation | ||
3 | +******************************************** | ||
4 | + | ||
5 | +This documentation is generated by the use of Sphinx and Pyreverse. | ||
6 | +Sphinx uses the `Restructured Text format <https://en.wikipedia.org/wiki/ReStructuredText>`_. | ||
7 | +The following links gives some informations about the syntax: | ||
8 | + | ||
9 | + * `Tutorial Sphinx 1 <https://deusyss.developpez.com/tutoriels/Python/SphinxDoc/>`_. | ||
10 | + * `Tutorial Sphinx 2 <https://www.mankier.com/1/sphinx-all>`_. | ||
11 | + * `Tutorial documentation <https://www.codeflow.site/fr/article/documenting-python-code>`_. | ||
12 | + * `Tutorial reST <https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`_. | ||
13 | + * `Tutorial Napoleon extension <https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#module-sphinx.ext.napoleon>`_. | ||
14 | + | ||
15 | +Installation of Sphinx and Pyreverse | ||
16 | +*********************************************** | ||
17 | + | ||
18 | +Procedure for Linux (root privileges): | ||
19 | + | ||
20 | +.. code-block:: bash | ||
21 | + | ||
22 | + sudo pip3 install sphinx | ||
23 | + sudo pip3 install rst2pdf | ||
24 | + sudo pip3 install pylint | ||
25 | + sudo pip3 install sphinx_pyreverse | ||
26 | + sudo pip3 install graphviz | ||
27 | + sudo apt-get install graphviz graphviz-dev | ||
28 | + sudo pip3 install pygraphviz | ||
29 | + | ||
30 | +Procedure for Windows (user xxx). First you must download and install | ||
31 | +`Graphviz <https://graphviz.org/>`_. Then: | ||
32 | + | ||
33 | +.. code-block:: bash | ||
34 | + | ||
35 | + cd c:\Users\xxx\Anaconda3\Scripts | ||
36 | + .\pip install -U Sphinx | ||
37 | + .\pip install rst2pdf | ||
38 | + .\conda install pyreverse | ||
39 | + .\conda install python-graphviz | ||
40 | + | ||
41 | +Generate the documentation | ||
42 | +*********************************************** | ||
43 | + | ||
44 | +To generate the documentation you must start to execute pyreverse | ||
45 | +followed by sphinx. | ||
46 | + | ||
47 | +Procedure pyreverse for Linux: | ||
48 | + | ||
49 | +.. code-block:: bash | ||
50 | + | ||
51 | + cd $PYROS | ||
52 | + pyreverse3 -p pyros -o png ../../pyros | ||
53 | + cp classes_*.png ../doc_images | ||
54 | + | ||
55 | +Procedure sphinx for Linux: | ||
56 | + | ||
57 | +.. code-block:: bash | ||
58 | + | ||
59 | + cd pyros/doc/rst | ||
60 | + sphinx-build -b html . ./../doc_html | ||
61 | + sphinx-build -b pdf . ./../doc_pdf | ||
62 | + | ||
63 | +Procedure pyreverse for Windows (user xxx): | ||
64 | + | ||
65 | +.. code-block:: bash | ||
66 | + | ||
67 | + cd astromecca\doc_rst\doc_pyreverse | ||
68 | + c:\Users\xxx\Anaconda3\Scripts\pyreverse -p pyros -o png ../../pyros | ||
69 | + copy classes_*.png ..\..\doc_images | ||
70 | + | ||
71 | +Procedure sphinx for Windows (user xxx): | ||
72 | + | ||
73 | +.. code-block:: bash | ||
74 | + | ||
75 | + cd astromecca\doc_rst | ||
76 | + C:\Users\xxx\Anaconda3\Scripts\sphinx-build -b html . .\..\doc_html | ||
77 | + C:\Users\xxx\Anaconda3\Scripts\sphinx-build -b pdf . .\..\doc_pdf | ||
78 | + |
@@ -0,0 +1,55 @@ | @@ -0,0 +1,55 @@ | ||
1 | +***************************************************** | ||
2 | +Welcome in the PyROS developer documentation | ||
3 | +***************************************************** | ||
4 | + | ||
5 | +.. image:: ../doc_images/logo-irap-couleur.png | ||
6 | + :height: 100px | ||
7 | + :align: center | ||
8 | + | ||
9 | ++------------------------------+--------------------------------------------+ | ||
10 | +| | IRAP | | Principal investigator: Etienne Pallier | | ||
11 | +| | 9 Avenue Colonel Roche | | etienne.pallier@irap.omp.eu | | ||
12 | +| | 31028 Toulouse Cedex 4 | | +33 5 61 55 66 48 | | ||
13 | +| | FRANCE | | http://pyros.omp.eu/ | | ||
14 | ++------------------------------+--------------------------------------------+ | ||
15 | + | ||
16 | +1. PyROS files | ||
17 | +************** | ||
18 | + | ||
19 | +Describe how the code is managed into folders. | ||
20 | + | ||
21 | +.. comments | ||
22 | + .. toctree:: | ||
23 | + :maxdepth: 3 | ||
24 | + | ||
25 | + using_mount_classes | ||
26 | + | ||
27 | +2. PyROS configuration files | ||
28 | +**************************** | ||
29 | + | ||
30 | +Describe how the code is managed into folders. | ||
31 | + | ||
32 | +.. toctree:: | ||
33 | + :maxdepth: 3 | ||
34 | + | ||
35 | + pyros_configuration | ||
36 | + | ||
37 | +3. Class and method documentation | ||
38 | +********************************* | ||
39 | + | ||
40 | +For developers of Python code in PyROS classes. | ||
41 | + | ||
42 | +.. toctree:: | ||
43 | + :maxdepth: 3 | ||
44 | + | ||
45 | + generate_documentation | ||
46 | + | ||
47 | +The classes of PyROS. | ||
48 | + | ||
49 | +.. comments | ||
50 | + .. toctree:: | ||
51 | + :maxdepth: 3 | ||
52 | + | ||
53 | + autodoc_pyros | ||
54 | + | ||
55 | + |