From 37659e6ba8ee4c0972b8a5c1e446383c76c74de0 Mon Sep 17 00:00:00 2001 From: Peter Mitri Date: Tue, 29 Oct 2024 14:18:34 +0100 Subject: [PATCH] try fix Signed-off-by: Peter Mitri --- .github/workflows/build-userguide.yml | 3 +- docs/README.md | 145 ++++++++++++++++---------- 2 files changed, 89 insertions(+), 59 deletions(-) diff --git a/.github/workflows/build-userguide.yml b/.github/workflows/build-userguide.yml index 25ff8316be..4032f73798 100644 --- a/.github/workflows/build-userguide.yml +++ b/.github/workflows/build-userguide.yml @@ -53,8 +53,7 @@ jobs: run: | PDF_NAME=antares-general-reference-guide.pdf cd docs/pdf-doc-generation-with-sphinx - chmod +x create_pdf_doc.sh - ./create_pdf_doc.sh $PDF_NAME + bash create_pdf_doc.sh $PDF_NAME echo "PDF_PATH=docs/pdf-doc-generation-with-sphinx/$PDF_NAME" >> $GITHUB_ENV echo "PDF_PATH_ASSET= [\"docs/pdf-doc-generation-with-sphinx/$PDF_NAME\"]" >> $GITHUB_ENV diff --git a/docs/README.md b/docs/README.md index 49c350d844..d70592d748 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,18 +1,23 @@ # Antares_Simulator documentation sources -This directory contains the source files for building the *Antares Simulator* [documentation website](https://antares-simulator.readthedocs.io/), -the PDF user guides that are published in every [release](https://github.com/AntaresSimulatorTeam/Antares_Simulator/releases), +This directory contains the source files for building the *Antares +Simulator* [documentation website](https://antares-simulator.readthedocs.io/), +the PDF user guides that are published in +every [release](https://github.com/AntaresSimulatorTeam/Antares_Simulator/releases), as well as the [Doxygen documentation](https://antaressimulatorteam.github.io/Antares_Simulator/doxygen/). Please help us keep this documentation alive: -- If you find that something is missing, outdated, or some mistake, report it in a [new issue](https://github.com/AntaresSimulatorTeam/Antares_Simulator/issues/new) + +- If you find that something is missing, outdated, or some mistake, report it in + a [new issue](https://github.com/AntaresSimulatorTeam/Antares_Simulator/issues/new) or, better yet, open a [pull request](https://github.com/AntaresSimulatorTeam/Antares_Simulator/compare)! -- If you add a new feature, change a parameter, change something in the technical workflow, etc., update these - sources in the same pull request. Pull requests that do not update the documentation when needed will not be approved. +- If you add a new feature, change a parameter, change something in the technical workflow, etc., update these + sources in the same pull request. Pull requests that do not update the documentation when needed will not be approved. ## Contents of this directory As noted above, these sources serve two purposes: + 1. Building the website 2. Building the PDF user guide 3. Building the Doxygen documentation @@ -20,80 +25,103 @@ As noted above, these sources serve two purposes: While most of the source code is common, some code is specific. ### Building the website -The website is hosted on [readthedocs](https://readthedocs.org/). The build workflow requires a configuration file which -is currently at the root of the project: [readthedocs.yml](../readthedocs.yml). This platform presents many advantages, + +The website is hosted on [readthedocs](https://readthedocs.org/). The build workflow requires a configuration file which +is currently at the root of the project: [readthedocs.yml](../readthedocs.yml). This platform presents many advantages, thanks to its workflow of automatic branch/tag building & publication: -- Multiple versions are activated: you can browse different versions of the documentation for different releases of *Antares Simulator* -- Pull requests are built automatically and the built status is reported in the PR's checks (`docs/readthedocs.org:antares-simulator`). - You can preview the built website inside this check (just click on `Details`), thus making it easier for reviewers to review changes of the docs. -HTML content of the website is built automatically from source files written in [Markdown](https://fr.wikipedia.org/wiki/Markdown), +- Multiple versions are activated: you can browse different versions of the documentation for different releases of + *Antares Simulator* +- Pull requests are built automatically and the built status is reported in the PR's checks ( + `docs/readthedocs.org:antares-simulator`). + You can preview the built website inside this check (just click on `Details`), thus making it easier for reviewers to + review changes of the docs. + +HTML content of the website is built automatically from source files written +in [Markdown](https://fr.wikipedia.org/wiki/Markdown), using [mkdocs](https://www.mkdocs.org/). The mkdocs configuration file is [mkdocs.yml](../mkdocs.yml), at the root of the project. -It contains all customization options for the website (for example, the theme used is [mkdocs-material](https://squidfunk.github.io/mkdocs-material/)). +It contains all customization options for the website (for example, the theme used +is [mkdocs-material](https://squidfunk.github.io/mkdocs-material/)). Here is the most common cases when you'll need to tweak this file: -- When you add a new page (written in Markdown), it is invisible by default. In order to make it visible, you have to + +- When you add a new page (written in Markdown), it is invisible by default. In order to make it visible, you have to add it to the navigation list of the website in mkdocs.yml (`nav` section). -- If you want to customize the theme's behaviour, you will probably have to change the mkdocs.yml file (refer to the +- If you want to customize the theme's behaviour, you will probably have to change the mkdocs.yml file (refer to the used theme's documentation first) -- If you want to customize mkdoc's behaviour, add plugins, css, etc., you need to change this file (refer to the +- If you want to customize mkdoc's behaviour, add plugins, css, etc., you need to change this file (refer to the [mkdocs doc](https://www.mkdocs.org/user-guide/) first) - -Sometimes, the possibilities offered by mkdocs & the used theme can be limiting. Mkdocs offers the possibility to use + +Sometimes, the possibilities offered by mkdocs & the used theme can be limiting. Mkdocs offers the possibility to use custom html & css code. Currently, two methods are used: -- Custom CSS: the [extra.css](stylesheets/extra.css) files contains custom CSS classes (read more about this [here](https://squidfunk.github.io/mkdocs-material/customization/#additional-css)). + +- Custom CSS: the [extra.css](stylesheets/extra.css) files contains custom CSS classes (read more about + this [here](https://squidfunk.github.io/mkdocs-material/customization/#additional-css)). Feel free to add classes to it if you find it necessary. -- HTML overrides: the [overrides](overrides) directory contains HTML files that override objects inherited from mkdocs - or its theme (read more about this [here](https://squidfunk.github.io/mkdocs-material/customization/#extending-the-theme)). +- HTML overrides: the [overrides](overrides) directory contains HTML files that override objects inherited from mkdocs + or its theme (read more about + this [here](https://squidfunk.github.io/mkdocs-material/customization/#extending-the-theme)). You can use this method when other, lighter methods (i.e. tweaking mkdocs.yml & CSS styles) are not enough. -When modifying the website content, you can easily preview the result on your PC by navigating to the root of the +When modifying the website content, you can easily preview the result on your PC by navigating to the root of the project and running: + ```bash mkdocs serve ``` + Then click on the produced link (most likely `http://127.0.0.1:8000/`) to open the website in your browser. -As long as this process is running, updating any doc file automatically regenerates the website and refreshed the browser. +As long as this process is running, updating any doc file automatically regenerates the website and refreshed the +browser. ### Building the PDF user guide -In every *Antares Simulator* [release](https://github.com/AntaresSimulatorTeam/Antares_Simulator/releases), -the user guide is printed to a PDF file and published in the assets. This document can be downloaded by users who -want to install *Antares Simulator* and be able to consult its documentation off-line. - -In practice, the PDF is generated automatically from Markdown files under [reference-guide](./user-guide) by -[Sphinx](https://www.sphinx-doc.org/) (using LaTeX). The script for this generation is in [pdf-doc-generation-with-sphinx/create_pdf_doc.sh](./pdf-doc-generation-with-sphinx/create_pdf_doc.sh); -it is automatically run by a GitHub [action](../.github/workflows/build-userguide.yml) during every release, and for -each pull request (in order to verify that the PDF builds). - -While the source material used for the PDF user guide are the same as the ones used for the mkdocs website (i.e. -Markdown files under `reference-guide`), some extra source files are needed: -- As for all Sphinx projects, this one needs a configuration file: [conf.py](./pdf-doc-generation-with-sphinx/source/conf.py). - This file allows you to customize the Sphinx build, in the same way mkdoks.yml allows you to customize mkdocs build. -- Sphinx navigation is built iteratively, using "index" files that refer to each other. The top-most index file is - [pdf-doc-generation-with-sphinx/source/index.rst](./pdf-doc-generation-with-sphinx/source/index.rst). It points to - [reference-guide/00-index.md](user-guide/00-index.md), which in turns points to other pages or indexes, - defining the whole navigation tree of the documentation. **This [reference-guide/00-index.md](user-guide/00-index.md) - file should be updated** in the same way mkdocs.yml is, in order to keep the navigation tree of the PDF document + +In every *Antares Simulator* [release](https://github.com/AntaresSimulatorTeam/Antares_Simulator/releases), +the user guide is printed to a PDF file and published in the assets. This document can be downloaded by users who +want to install *Antares Simulator* and be able to consult its documentation off-line. + +In practice, the PDF is generated automatically from Markdown files under [user-guide](./user-guide) by +[Sphinx](https://www.sphinx-doc.org/) (using LaTeX). The script for this generation is +in [pdf-doc-generation-with-sphinx/create_pdf_doc.sh](./pdf-doc-generation-with-sphinx/create_pdf_doc.sh); +it is automatically run by a GitHub [action](../.github/workflows/build-userguide.yml) during every release, and for +each pull request (in order to verify that the PDF builds). + +While the source material used for the PDF user guide are the same as the ones used for the mkdocs website (i.e. +Markdown files under `user-guide`), some extra source files are needed: + +- As for all Sphinx projects, this one needs a configuration + file: [conf.py](./pdf-doc-generation-with-sphinx/source/conf.py). + This file allows you to customize the Sphinx build, in the same way mkdoks.yml allows you to customize mkdocs build. +- Sphinx navigation is built iteratively, using "index" files that refer to each other. The top-most index file is + [pdf-doc-generation-with-sphinx/source/index.rst](./pdf-doc-generation-with-sphinx/source/index.rst). It points to + [user-guide/00-index.md](user-guide/00-index.md), which in turns points to other pages or indexes, + defining the whole navigation tree of the documentation. **This [user-guide/00-index.md](user-guide/00-index.md) + file should be updated** in the same way mkdocs.yml is, in order to keep the navigation tree of the PDF document synchronized with the navigation tree of the mkdocs website. -When modifying the user guide content, you can easily preview the resulting PDF on your PC by navigating to the +When modifying the user guide content, you can easily preview the resulting PDF on your PC by navigating to the root of the project and running: + ```bash cd docs/pdf-doc-generation-with-sphinx -bash create_pdf_doc.sh reference-guide.pdf +bash create_pdf_doc.sh user-guide.pdf ``` -Sphinx will create a `reference-guide.pdf` file in `docs/pdf-doc-generation-with-sphinx`. + +Sphinx will create a `user-guide.pdf` file in `docs/pdf-doc-generation-with-sphinx`. ### Doxygen + [//]: # (TODO) -We strive to enrich code documentation as it evolves. The doxygen doc is generated automatically each time the develop -branch is updated. It is hosted [here](https://antaressimulatorteam.github.io/Antares_Simulator/doxygen), and can also -be generated locally with the follow command at the root of the project: - -**doxygen-executable** docs/Doxyfile - -If you'd like the same rendering as the one published checkout [doxygen-awesome-css](https://github.com/jothepro/doxygen-awesome-css) -and do this step before: +We strive to enrich code documentation as it evolves. The doxygen doc is generated automatically each time the develop +branch is updated. It is hosted [here](https://antaressimulatorteam.github.io/Antares_Simulator/doxygen), and can also +be generated locally with the follow command at the root of the project: + +**doxygen-executable** docs/Doxyfile + +If you'd like the same rendering as the one published +checkout [doxygen-awesome-css](https://github.com/jothepro/doxygen-awesome-css) +and do this step before: + ```bash git clone https://github.com/jothepro/doxygen-awesome-css.git cd doxygen-awesome-css @@ -103,12 +131,15 @@ git apply ../docs/antares-simulator-doxygen.patch ## Extra considerations -Like mentioned above, the same source material is used to automatically generate three different formats (mkdocs website, -PDF, doxygen website). When writing pages that have to be published in more than one format, please make sure the +Like mentioned above, the same source material is used to automatically generate three different formats (mkdocs +website, +PDF, doxygen website). When writing pages that have to be published in more than one format, please make sure the syntax you are using is compatible with all the target formats. Here is a **non-exhaustive** list of points to watch out for: -- When you add a page, make sure you add it to all target supports. For instance, adding a page to the mkdocs website - requires creating a `nav` entry in the [mkdocs.yml](../mkdocs.yml) file, while adding it to the Sphinx PDF requires - adding an extra entry to an existing index.md file, and, sometimes, creating an extra index.md file (to add a section). -- Do not use non-standard characters (such as emojis) in the user guide, as they cannot be rendered by LaTeX + +- When you add a page, make sure you add it to all target supports. For instance, adding a page to the mkdocs website + requires creating a `nav` entry in the [mkdocs.yml](../mkdocs.yml) file, while adding it to the Sphinx PDF requires + adding an extra entry to an existing index.md file, and, sometimes, creating an extra index.md file (to add a + section). +- Do not use non-standard characters (such as emojis) in the user guide, as they cannot be rendered by LaTeX in PDF.