developper doc

This commit is contained in:
gwen 2024-07-09 18:10:15 +02:00
parent d5661511da
commit 620f09a041
3 changed files with 174 additions and 6 deletions

24
docs/Makefile Normal file
View file

@ -0,0 +1,24 @@
# 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 = .
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)
# Live reload site documents for local development
livehtml:
sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

View file

@ -5,15 +5,60 @@ Developer notes
This section is intended to be usefull for team developers only. This section is intended to be usefull for team developers only.
Developer installation process
------------------------------------
Quick installation process The conventional installation process is as usual with the python installer, that is::
---------------------------------------
This process describes how to install and run the project locally, e.g. for development purposes. pip install rougail
*Nota*: command is to be executed through the terminal This section describes how to install and run the project locally, e.g. for development purposes,
so we won't use this installation way, we will clone `rougail` directly from the repository.
The best way to work with the library in development mode is to install a virtual
environment::
`pip install rougail` python -m"venv" .venv
then install the dependencies::
./.venv/bin/pip3 install ruamel.yaml
./.venv/bin/pip3 install pydantic
./.venv/bin/pip3 install jinja2
.. note:: Please have a look at the `pyproject.toml` install configuration file.
There is a `dependencies` section.
.. code-block:: python
dependencies = [
"ruamel.yaml ~= 0.17.40",
"pydantic ~= 2.5.2",
"jinja2 ~= 3.1.2",
"tiramisu ~= 4.1.0"
]
Then we need to install two libraries
- rougail::
git clone https://forge.cloud.silique.fr/stove/rougail.git
- tiramisu::
git clone https://forge.cloud.silique.fr/stove/tiramisu.git
The we put it in the :envvar:`PATH`::
export PYTHONPATH=$PYTHONPATH:'./tiramisu/'
export PYTHONPATH=$PYTHONPATH:'./rougail/src'
You can put these two line in a bash script, named for example :file:`export_path.sh`,
then source it::
source export_path.sh
To run rougail and see that everything is doing well, you can use the
:ref:`hello world sample script <helloworld>`.
Code quality Code quality
--------------- ---------------
@ -48,7 +93,7 @@ You need to:
Coding standard Coding standard
------------------ ------------------
We use black Pre-commit launches black and pep8 validators.
.. code-block:: yaml .. code-block:: yaml
@ -58,3 +103,101 @@ We use black
- id: black - id: black
And some YAML and JSON validators. And some YAML and JSON validators.
Test framework
-------------------
Our test framework lives in the `tests` project's folder.
You need to install the pytest tool::
./.venv/bin/pip3 install pytest
Here is a sample test session::
../.venv/bin/pytest -s tests/test_1_flattener.py
==================== test session starts =====================
platform linux -- Python 3.12.3, pytest-8.2.2, pluggy-1.5.0
rootdir: /home/ubuntu/workplace/rougail
configfile: pyproject.toml
collected 586 items
tests/test_1_flattener.py ............................................
================== short test summary info ===================
FAILED tests/test_1_flattener.py
FAILED tests/test_1_flattener.py
========== 2 failed, 584 passed, 1 warning in 5.69s ==========
.. note:: For the moment, the tests must be lauched at the `rougail`'s root project.
The tests that live in these files:
- `test_1_flattener.py`
- `test_1_flattener.py`
Are "automatic" tests, that is
- they run `fixtures in the pytest way <https://docs.pytest.org/en/7.1.x/how-to/fixtures.html>`_
- they require a specific tree structure
The tree structure is in the `rougail/tests/dictionaries` folder, you need to
create a folder that start with a specific test code number, for example::
80no_leadership_index2
80no_version
...
80unknown_type
80unsupported_version
80valid_enum_multi_param
80valid_enum_multi_variable
inside theses folders, the directory tree structure shall always be the same::
__init__.py dictionaries makedict tiramisu
To add a new test, you use a script that finds the test code already in use
like this one:
.. code-block:: shell
:caption: The :file:`find_id.sh` script
for i in $(seq 1 100); do
grep -qRI "$i," src/rougail/
if [ ! "$?" = "0" ]; then
echo "======================== $i ============================";
exit 0
fi
done
then find a name for your tests. The test directory starts with the test number::
<test_number><test_name>
then put the rougail yaml file in the :file:`<test_number><test_name>/dictionaries`
folder.
.. note:: you need to run the test one, the test will populate the tiramisu code
in the `tiramisu` folder, just check the code and if the generated code looks
like what you expected, you can keep it as an expected test result.
HTML documentation
--------------------
To generate locally the documentation :
- install sphinx: `pip install sphinx`
- install the read the docs theme with `pip3 install sphinx_rtd_theme`
- install the `sphinx-lesson <https://coderefinery.github.io/sphinx-lesson/>`_
package with `pip3 install sphinx-lesson`
Or more simply type `pip install -r requirements.txt` in the `docs` project's folder.
To generate the doc, type `make html` in the `docs` folder.
The go to the :file:`docs/_build/html` folder and launch a micro-web server,
for example::
python -m"http.server"
Open your web browser and nagivate in the docs at the `http://localhost:8000` url.

View file

@ -124,6 +124,7 @@ Here is the tree structure we want to have::
.. code-block:: yaml .. code-block:: yaml
:caption: The `hello.yaml` file :caption: The `hello.yaml` file
:name: helloworld
--- ---
version: '1.1' version: '1.1'