From 8e24b5a7227b636eace6aa31f0c7b978ddaea597 Mon Sep 17 00:00:00 2001 From: LE BRETON Come Date: Wed, 25 Sep 2024 09:36:16 +0200 Subject: [PATCH] Improve readability of doc for doc gen. --- docs/README.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/README.md b/docs/README.md index 0d86c733e..f5f2763fb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,6 +2,8 @@ The documentation is based on a combination of Sphinx parsing Exhale rst output genrated from Doxygen xml output. +## Dependencies + It requires installing some dependencies, installation that can be leverage using pip. To install the dependencies to build the documentation: @@ -9,17 +11,22 @@ To install the dependencies to build the documentation: ``` shell pip install -r docs/requirements.txt ``` +## Documentation generation Following that, the corese-core documentation can be generated through a single call to sphinx-multiversion from the root directory of corese-core: ``` shell sphinx-multiversion docs/source build/html -D 'exhale_args.containmentFolder=${sourcedir}/java_api' -v ``` +## Switcher generation + +- To navigate between versions by means of the switcher (the dropdown list indicating the available version), the switcher.json object must be generated. +- To improve navigability, a landing page must also be generated to redirect to the latest version of the documentation. -To navigate between versions by means of the switcher (the dropdown list idicating the available version), the switcher.json object must be generated. To improve navigability, a landing page must also be generated to redirect to the latest version of the documentation. To this end a script must be executed and write the output to the output html directory: +To this end a script must be executed and write the output to the output html directory: ```shell ./docs/switcher_generator.sh build/html/switcher.json build/html/index.html ``` -Both sphinx-multiversion and switcher_generator work on tags following the ``^v[0-9]+\.[0-9]+\.[0-9]+$` syntax, they are ordered by ref name. +Both sphinx-multiversion and switcher_generator work on tags following the ``^v[0-9]+\.[0-9]+\.[0-9]+$` syntax and ordered by refname.