From afd6c27bfec867ba74ffdd6cd24cc39981fe835a Mon Sep 17 00:00:00 2001 From: Foucher Alexandre Date: Thu, 25 Jan 2024 11:33:17 +0100 Subject: [PATCH] add python example --- cpp-example/docs/source/conf.py | 48 +++++----- cpp-example/readme.md | 4 +- py-example/.gitignore | 1 + py-example/docs/.gitignore | 2 + py-example/docs/Makefile | 20 +++++ py-example/docs/make.bat | 35 ++++++++ .../_templates/autosummary/attribute.rst | 13 +++ .../source/_templates/autosummary/base.rst | 17 ++++ .../source/_templates/autosummary/class.rst | 27 ++++++ .../source/_templates/autosummary/member.rst | 13 +++ .../source/_templates/autosummary/method.rst | 13 +++ .../_templates/autosummary/minimal_module.rst | 8 ++ .../source/_templates/autosummary/module.rst | 40 +++++++++ py-example/docs/source/conf.py | 41 +++++++++ py-example/docs/source/index.rst | 29 ++++++ py-example/pyexample/Driver.py | 44 +++++++++ py-example/pyexample/__init__.py | 0 py-example/readme.md | 90 +++++++++++++++++++ 18 files changed, 417 insertions(+), 28 deletions(-) create mode 100644 py-example/.gitignore create mode 100644 py-example/docs/.gitignore create mode 100644 py-example/docs/Makefile create mode 100644 py-example/docs/make.bat create mode 100644 py-example/docs/source/_templates/autosummary/attribute.rst create mode 100644 py-example/docs/source/_templates/autosummary/base.rst create mode 100644 py-example/docs/source/_templates/autosummary/class.rst create mode 100644 py-example/docs/source/_templates/autosummary/member.rst create mode 100644 py-example/docs/source/_templates/autosummary/method.rst create mode 100644 py-example/docs/source/_templates/autosummary/minimal_module.rst create mode 100644 py-example/docs/source/_templates/autosummary/module.rst create mode 100644 py-example/docs/source/conf.py create mode 100644 py-example/docs/source/index.rst create mode 100644 py-example/pyexample/Driver.py create mode 100644 py-example/pyexample/__init__.py create mode 100644 py-example/readme.md diff --git a/cpp-example/docs/source/conf.py b/cpp-example/docs/source/conf.py index a54f431..db7251c 100644 --- a/cpp-example/docs/source/conf.py +++ b/cpp-example/docs/source/conf.py @@ -11,39 +11,35 @@ copyright = '2024, Alexandre Foucher' author = 'Alexandre Foucher' release = '1.0' +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_rtd_theme' +html_static_path = ['_static'] + # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = [ - 'breathe', - 'exhale' -] - -breathe_projects = {"My Project": "../build/_doxygen/xml"} -breathe_default_project = "My Project" - -exhale_args = { - # These arguments are required - "containmentFolder": "./api", - "rootFileName": "library_root.rst", - "doxygenStripFromPath": "..", - # Heavily encouraged optional argument (see docs) - "rootFileTitle": "Library API", - # Suggested optional arguments - "createTreeView": True, - # TIP: if using the sphinx-bootstrap-theme, you need - # "treeViewIsBootstrap": True, - "exhaleExecutesDoxygen": True, - "exhaleDoxygenStdin": "INPUT = ../../include" -} +extensions = [] templates_path = ['_templates'] exclude_patterns = [] language = 'fr' -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output +# ----------------------------------------------------------------------------- -html_theme = 'shibuya' -html_static_path = ['_static'] +extensions += ['breathe','exhale'] + +breathe_projects = {"My Project": "../build/_doxygen/xml"} +breathe_default_project = "My Project" + +exhale_args = { + "containmentFolder": "./api", + "rootFileName": "library_root.rst", + "doxygenStripFromPath": "..", + "rootFileTitle": "Library API", + "createTreeView": True, + "exhaleExecutesDoxygen": True, + "exhaleDoxygenStdin": "INPUT = ../../include" +} \ No newline at end of file diff --git a/cpp-example/readme.md b/cpp-example/readme.md index fed95ce..0c276c8 100644 --- a/cpp-example/readme.md +++ b/cpp-example/readme.md @@ -8,7 +8,7 @@ ```sh # Installing dependencies -pip3 install sphinx shibuya breathe exhale +pip3 install sphinx sphinx_rtd_theme breathe exhale sudo apt-get install doxygen # Generating documentation @@ -85,5 +85,5 @@ The best way is to go in `source/index.rst` and add `api/library_root` as an ent Inside the `docs` directory you can now execute `make html` ! You can acces it through `docs/build/html/index.html`. -> :warning: **Warning** +> **Warning** > Do not store the `build` folder in your remote storage, if you use `git` simply copy the `.gitignore` inside `cpp-example/docs` and paste it to your `docs` folder. \ No newline at end of file diff --git a/py-example/.gitignore b/py-example/.gitignore new file mode 100644 index 0000000..b42097e --- /dev/null +++ b/py-example/.gitignore @@ -0,0 +1 @@ +**/__pycache__/ \ No newline at end of file diff --git a/py-example/docs/.gitignore b/py-example/docs/.gitignore new file mode 100644 index 0000000..2acb705 --- /dev/null +++ b/py-example/docs/.gitignore @@ -0,0 +1,2 @@ +build/ +source/api \ No newline at end of file diff --git a/py-example/docs/Makefile b/py-example/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/py-example/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/py-example/docs/make.bat b/py-example/docs/make.bat new file mode 100644 index 0000000..747ffb7 --- /dev/null +++ b/py-example/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/py-example/docs/source/_templates/autosummary/attribute.rst b/py-example/docs/source/_templates/autosummary/attribute.rst new file mode 100644 index 0000000..9e0eaa2 --- /dev/null +++ b/py-example/docs/source/_templates/autosummary/attribute.rst @@ -0,0 +1,13 @@ +:orphan: + +{{ fullname | escape | underline}} + +.. currentmodule:: {{ module }} + +attribute + +.. auto{{ objtype }}:: {{ fullname | replace("numpy.", "numpy::") }} + +{# In the fullname (e.g. `numpy.ma.MaskedArray.methodname`), the module name +is ambiguous. Using a `::` separator (e.g. `numpy::ma.MaskedArray.methodname`) +specifies `numpy` as the module name. #} diff --git a/py-example/docs/source/_templates/autosummary/base.rst b/py-example/docs/source/_templates/autosummary/base.rst new file mode 100644 index 0000000..91bfff9 --- /dev/null +++ b/py-example/docs/source/_templates/autosummary/base.rst @@ -0,0 +1,17 @@ +{% if objtype == 'property' %} +:orphan: +{% endif %} + +{{ fullname | escape | underline}} + +.. currentmodule:: {{ module }} + +{% if objtype == 'property' %} +property +{% endif %} + +.. auto{{ objtype }}:: {{ fullname | replace("numpy.", "numpy::") }} + +{# In the fullname (e.g. `numpy.ma.MaskedArray.methodname`), the module name +is ambiguous. Using a `::` separator (e.g. `numpy::ma.MaskedArray.methodname`) +specifies `numpy` as the module name. #} diff --git a/py-example/docs/source/_templates/autosummary/class.rst b/py-example/docs/source/_templates/autosummary/class.rst new file mode 100644 index 0000000..64c1b11 --- /dev/null +++ b/py-example/docs/source/_templates/autosummary/class.rst @@ -0,0 +1,27 @@ +{% extends "!autosummary/class.rst" %} + +{% block methods %} +{% if methods %} + .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages. + .. autosummary:: + :toctree: + {% for item in all_methods %} + {%- if not item.startswith('_') or item in ['__call__'] %} + {{ name }}.{{ item }} + {%- endif -%} + {%- endfor %} +{% endif %} +{% endblock %} + +{% block attributes %} +{% if attributes %} + .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages. + .. autosummary:: + :toctree: + {% for item in all_attributes %} + {%- if not item.startswith('_') %} + {{ name }}.{{ item }} + {%- endif -%} + {%- endfor %} +{% endif %} +{% endblock %} diff --git a/py-example/docs/source/_templates/autosummary/member.rst b/py-example/docs/source/_templates/autosummary/member.rst new file mode 100644 index 0000000..c0dcd5e --- /dev/null +++ b/py-example/docs/source/_templates/autosummary/member.rst @@ -0,0 +1,13 @@ +:orphan: + +{{ fullname | escape | underline}} + +.. currentmodule:: {{ module }} + +member + +.. auto{{ objtype }}:: {{ fullname | replace("numpy.", "numpy::") }} + +{# In the fullname (e.g. `numpy.ma.MaskedArray.methodname`), the module name +is ambiguous. Using a `::` separator (e.g. `numpy::ma.MaskedArray.methodname`) +specifies `numpy` as the module name. #} diff --git a/py-example/docs/source/_templates/autosummary/method.rst b/py-example/docs/source/_templates/autosummary/method.rst new file mode 100644 index 0000000..0dd2263 --- /dev/null +++ b/py-example/docs/source/_templates/autosummary/method.rst @@ -0,0 +1,13 @@ +:orphan: + +{{ fullname | escape | underline}} + +.. currentmodule:: {{ module }} + +method + +.. auto{{ objtype }}:: {{ fullname | replace("numpy.", "numpy::") }} + +{# In the fullname (e.g. `numpy.ma.MaskedArray.methodname`), the module name +is ambiguous. Using a `::` separator (e.g. `numpy::ma.MaskedArray.methodname`) +specifies `numpy` as the module name. #} diff --git a/py-example/docs/source/_templates/autosummary/minimal_module.rst b/py-example/docs/source/_templates/autosummary/minimal_module.rst new file mode 100644 index 0000000..f0d9f00 --- /dev/null +++ b/py-example/docs/source/_templates/autosummary/minimal_module.rst @@ -0,0 +1,8 @@ +{{ fullname | escape | underline}} + +.. automodule:: {{ fullname }} + + {% block docstring %} + {% endblock %} + + diff --git a/py-example/docs/source/_templates/autosummary/module.rst b/py-example/docs/source/_templates/autosummary/module.rst new file mode 100644 index 0000000..e1f428d --- /dev/null +++ b/py-example/docs/source/_templates/autosummary/module.rst @@ -0,0 +1,40 @@ +{% extends "!autosummary/module.rst" %} + +{# This file is almost the same as the default, but adds :toctree: to the autosummary directives. + The original can be found at `sphinx/ext/autosummary/templates/autosummary/module.rst`. #} + +{% block attributes %} +{% if attributes %} + .. rubric:: Module Attributes + + .. autosummary:: + :toctree: + {% for item in attributes %} + {{ item }} + {%- endfor %} +{% endif %} +{% endblock %} + +{% block functions %} +{% if functions %} + .. rubric:: Functions + + .. autosummary:: + :toctree: + {% for item in functions %} + {{ item }} + {%- endfor %} +{% endif %} +{% endblock %} + +{% block classes %} +{% if classes %} + .. rubric:: Classes + + .. autosummary:: + :toctree: + {% for item in classes %} + {{ item }} + {%- endfor %} +{% endif %} +{% endblock %} diff --git a/py-example/docs/source/conf.py b/py-example/docs/source/conf.py new file mode 100644 index 0000000..825a8e4 --- /dev/null +++ b/py-example/docs/source/conf.py @@ -0,0 +1,41 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'py-example' +copyright = '2024, Alexandre Foucher' +author = 'Alexandre Foucher' +release = '1.0' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [] + +templates_path = ['_templates'] +exclude_patterns = [] + +language = 'fr' + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "sphinx_rtd_theme" +html_static_path = ['_static'] + +import os +import sys +sys.path.insert(0, os.path.abspath('../..')) +print(os.path.abspath('../..')) + +extensions += [ + 'sphinx.ext.napoleon', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary' +] + +autosummary_generate = True diff --git a/py-example/docs/source/index.rst b/py-example/docs/source/index.rst new file mode 100644 index 0000000..a966557 --- /dev/null +++ b/py-example/docs/source/index.rst @@ -0,0 +1,29 @@ +.. py-example documentation master file, created by + sphinx-quickstart on Wed Jan 24 17:28:52 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to py-example's documentation! +====================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + api + +API +--- + +.. autosummary:: + :toctree: api + :recursive: + + pyexample + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/py-example/pyexample/Driver.py b/py-example/pyexample/Driver.py new file mode 100644 index 0000000..c574a90 --- /dev/null +++ b/py-example/pyexample/Driver.py @@ -0,0 +1,44 @@ +class Driver: + """ + Driver for specific sensor + + Attributes + ---------- + name : str + Name of the sensor + + Methods + ------- + write(buffer): + Send data to the sensor. + """ + + def __init__(self, name:str): + """ + Constructs all the necessary attributes for the driver object. + + Parameters + ---------- + name : str + Name of the sensor + """ + + self.name = name + + def write(self, buffer:str) -> int: + """ + Send data buffer to the sensor. + + Parameters + ---------- + buffer : str + Data buffer to be send + + Returns + ------- + status_code : int + status code of the operation SUCCES, FAILURE + """ + + # Do something + return 0 \ No newline at end of file diff --git a/py-example/pyexample/__init__.py b/py-example/pyexample/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/py-example/readme.md b/py-example/readme.md new file mode 100644 index 0000000..0043aef --- /dev/null +++ b/py-example/readme.md @@ -0,0 +1,90 @@ +
+ +# Sphinx documentation from python docstring + +
+ +## :tv: Demo + +```sh +# Installing dependencies +pip3 install sphinx sphinx_rtd_theme + +# Generating documentation +cd docs +make html +``` + +You can acces it through `docs/build/html/index.html`. + +## :rocket: How to use it ? + +**1. Generate the sphinx structure** + +In a first place, you need to generate the sphinx documentation using +the command `sphinx-quickstart` inside a `docs` folder as below : + +```sh +mkdir docs +cd docs +sphinx-quickstart --sep -l "fr" -r 1.0 . +``` + +Now your project structure should look like this + +``` +my_project/ +├── docs/ +│ ├── build/ +│ ├── source/ +│ ├── conf.py +│ ├── make.bat +│ └── Makefie +├── src +└── readme.md +``` + +**2. Edit sphinx config** + +And lastly you need to copy the next script at the end of the `conf.py` file. +This script add the needed configuration to allow sphinx to generate the documentation from the docstring inside all your `.py` files. +(You don't need to change anything in the next configuration) + +```py +import os +import sys +sys.path.insert(0, os.path.abspath('../..')) +print(os.path.abspath('../..')) + +extensions += [ + 'sphinx.ext.napoleon', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary' +] + +autosummary_generate = True +``` + +**3. Link the doc to a toctree** + +Now you need to link the documentation somewhere in your sphinx `rst` file. +The best way is to go in `source/index.rst` and add `api/library_root` as an entry of the toctree. + +```css +.. autosummary:: + :toctree: api + :recursive: + + +``` + +> **Info** +> In our case `` is `pyexample` + +**4. Now you can generate !** + +Inside the `docs` directory you can now execute `make html` ! +You can acces it through `docs/build/html/index.html`. + +> **Warning** +> Do not store the `build` folder in your remote storage, if you use `git` simply copy the `.gitignore` inside `py-example/docs` and paste it to your `docs` folder. \ No newline at end of file