add python example

This commit is contained in:
Alexandre Foucher 2024-01-25 11:33:17 +01:00
parent 506be8be5c
commit afd6c27bfe
18 changed files with 417 additions and 28 deletions

View file

@ -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"
}

View file

@ -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.

1
py-example/.gitignore vendored Normal file
View file

@ -0,0 +1 @@
**/__pycache__/

2
py-example/docs/.gitignore vendored Normal file
View file

@ -0,0 +1,2 @@
build/
source/api

20
py-example/docs/Makefile Normal file
View file

@ -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)

35
py-example/docs/make.bat Normal file
View file

@ -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

View file

@ -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. #}

View file

@ -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. #}

View file

@ -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 %}

View file

@ -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. #}

View file

@ -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. #}

View file

@ -0,0 +1,8 @@
{{ fullname | escape | underline}}
.. automodule:: {{ fullname }}
{% block docstring %}
{% endblock %}

View file

@ -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 %}

View file

@ -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

View file

@ -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`

View file

@ -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

View file

90
py-example/readme.md Normal file
View file

@ -0,0 +1,90 @@
<div align="center">
# Sphinx documentation from python docstring
</div>
## :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:
<source_directory>
```
> **Info**
> In our case `<source_directory>` 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.