developper doc

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)

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

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'