developper doc
This commit is contained in:
gwen
parent
d5661511da
commit
620f09a041
3 changed files with 174 additions and 6 deletions
24
docs/Makefile
Normal file
24
docs/Makefile
Normal 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)
|
||||
|
|
@ -5,15 +5,60 @@ Developer notes
|
|||
|
||||
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
|
||||
---------------
|
||||
|
|
@ -48,7 +93,7 @@ You need to:
|
|||
Coding standard
|
||||
------------------
|
||||
|
||||
We use black
|
||||
Pre-commit launches black and pep8 validators.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
|
@ -58,3 +103,101 @@ We use black
|
|||
- id: black
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -124,6 +124,7 @@ Here is the tree structure we want to have::
|
|||
|
||||
.. code-block:: yaml
|
||||
:caption: The `hello.yaml` file
|
||||
:name: helloworld
|
||||
|
||||
---
|
||||
version: '1.1'
|
||||
|
|
|
|||
Loading…
Reference in a new issue