From 620f09a04148da93f546eb0c77b4c8edcde58c73 Mon Sep 17 00:00:00 2001 From: gwen Date: Tue, 9 Jul 2024 18:10:15 +0200 Subject: [PATCH] developper doc --- docs/Makefile | 24 +++++++ docs/developer.rst | 155 ++++++++++++++++++++++++++++++++++++++-- docs/gettingstarted.rst | 1 + 3 files changed, 174 insertions(+), 6 deletions(-) create mode 100644 docs/Makefile diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..41c94e2d5 --- /dev/null +++ b/docs/Makefile @@ -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) diff --git a/docs/developer.rst b/docs/developer.rst index 8fafd92fb..19dd2569b 100644 --- a/docs/developer.rst +++ b/docs/developer.rst @@ -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 `. 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 `_ +- 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:: + + + +then put the rougail yaml file in the :file:`/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 `_ + 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. diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst index 894d12c35..e3d4220e6 100644 --- a/docs/gettingstarted.rst +++ b/docs/gettingstarted.rst @@ -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'