Documentation reorganization (#2024)

This PR includes a reorganization of the documentation content structure, plus some extra content: - The website now has a richer tree, most of the content was redispatched in the new pages: - the top-most categories are "user guide" (instead of "reference guide") and "developer guide" (instead of "build") - the "user guide" is now easier to read: - with a focus on Antares_Simulator's two main features: solver and ts-generator - the other features are briefly documented but marked as deprecated - each of the features now has a new "parameters" page - the solver now has a new "heuristics" page intended to document all the heuristics used by the solver - both features have "inputs, outputs and command line" pages - The PDF generation action is now run on same branches as other actions, in order to check that the PDF builds correctly - New README in the docs directory to explain how developers should maintain the docs - Some overall updates & harmonization - There is still a lot of work to be done (at least the tasks marked with a "TODO" comment) The resulting doc can be previewed in the readthedocs automatic check or here: https://antares-simulator--2024.org.readthedocs.build/en/2024/ --------- Co-authored-by: abdoulbari zaher <[email protected]> Co-authored-by: Florian OMNES <[email protected]>
AntaresSimulatorTeam · May 21, 2024 · f92325d · f92325d
1 parent f315c2f
commit f92325d
Show file tree

Hide file tree

Showing 87 changed files with 3,811 additions and 2,530 deletions.
diff --git a/.github/workflows/build-userguide.yml b/.github/workflows/build-userguide.yml
@@ -6,6 +6,10 @@ on:
   push:
     branches:
       - release/*
+      - feature/*
+      - features/*
+      - fix/*
+      - issue-*
       - doc/*
       - dependabot/*
   workflow_call:

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -15,7 +15,7 @@ Antares Simulator team will be pleased to have developers join our project.
 
 You can find all the steps needed to build & install Antares Simulator in 
 the [documentation website](https://antares-simulator.readthedocs.io/)
-or [its sources](docs/build/0-Introduction.md).
+or [its sources](docs/developer-guide/0-Introduction.md).
 
 ### Branch names
 Currently, CI is run only for specific branch names:

diff --git a/NEWS.md b/NEWS.md
@@ -1,4 +1,4 @@
 Antares Changelog
 =================
 
-Please refer to [docs/CHANGELOG.md](docs/CHANGELOG.md)
+Please refer to [docs/developer-guide/CHANGELOG.md](docs/developer-guide/CHANGELOG.md)
diff --git a/README.md b/README.md
@@ -29,14 +29,14 @@ In May 2018, RTE decided to release the project under the GPLv3 license.
 In January 2024, RTE, as the exclusive copyright owner, decided to switch from the GPLv3 to the MPLv2 license,
 starting with the 9.0 version of Antares Simulator.
 
-The GUI is deprecated in favor of [Antares Web](https://github.com/AntaresSimulatorTeam/AntaREST).
+The GUI is deprecated in favor of [Antares Web](https://antares-web.readthedocs.io).
 
 # Links:
 
 - Antares website:  https://antares-simulator.org
 - RTE web site : http://www.rte-france.com/
 - Doxygen code documentation: https://antaressimulatorteam.github.io/Antares_Simulator/doxygen
-- Antares Web: https://github.com/AntaresSimulatorTeam/AntaREST
+- Antares Web: https://antares-web.readthedocs.io
 
 # Installation
 
@@ -49,7 +49,7 @@ This software suite has been tested under:
 
 Antares Simulator is built using CMake.
 For installation instructions, please visit the [documentation website](https://antares-simulator.readthedocs.io/) 
-or [its sources](docs/build/0-Introduction.md).
+or [its sources](docs/developer-guide/0-Introduction.md).
 
 # Source Code Content
 

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,114 @@
+# 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), 
+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) 
+  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.  
+
+## 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
+
+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, 
+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), 
+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/)). 
+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 
+  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 
+  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 
+  [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 
+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)). 
+  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)). 
+  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 
+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. 
+
+### 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 
+  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 
+root of the project and running:
+```bash
+cd docs/pdf-doc-generation-with-sphinx
+bash create_pdf_doc.sh reference-guide.pdf
+```
+Sphinx will create a `reference-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:  
+```bash
+git clone https://github.com/jothepro/doxygen-awesome-css.git
+cd doxygen-awesome-css
+git checkout v2.2.1
+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 
+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 
+  in PDF.
diff --git a/docs/build/0-Introduction.md → docs/developer-guide/0-Overview.md b/docs/build/0-Introduction.md → docs/developer-guide/0-Overview.md
@@ -3,7 +3,7 @@ hide:
  - toc
 ---
 
-# Introduction
+# Overview
 
 *ANTARES* is developed mainly in **C++**
 

diff --git a/docs/build/1-Development-requirements.md → ...loper-guide/1-Development-requirements.md b/docs/build/1-Development-requirements.md → ...loper-guide/1-Development-requirements.md
diff --git a/docs/build/2-Dependencies-install.md → ...developer-guide/2-Dependencies-install.md b/docs/build/2-Dependencies-install.md → ...developer-guide/2-Dependencies-install.md
diff --git a/docs/build/3-Build.md → docs/developer-guide/3-Build.md b/docs/build/3-Build.md → docs/developer-guide/3-Build.md
@@ -42,10 +42,10 @@ Here is a list of mandatory or optional CMake configuration options:
 
 | Option                | Mandatory | Description                                                                      | Expected value                         | Default value                                             |
 |:----------------------|-----------|----------------------------------------------------------------------------------|----------------------------------------|-----------------------------------------------------------|
-| `CMAKE_C_COMPILER`    | **yes**   | Select C compiler                                                                | `gcc_-10`                               |                                                           |
+| `CMAKE_C_COMPILER`    | **yes**   | Select C compiler                                                                | `gcc_-10`                              |                                                           |
 | `CMAKE_CXX_COMPILER`  | **yes**   | Select C++ compiler                                                              | `g++-10`                               |                                                           |
 | `CMAKE_BUILD_TYPE`    | **yes**   | Define build type                                                                | `Release` / `Debug` / `RelWithDebInfo` |                                                           |
-| `BUILD_UI`            | no        | Enable or disable Antares Simulator UI compilation                               | `ON` / `OFF`                           | `ON`                                                      |
+| `BUILD_UI`            | no        | Enable or disable Antares Simulator UI[^1] compilation                           | `ON` / `OFF`                           | `ON`                                                      |
 | `BUILD_ALL`           | no        | Enable build of ALL external libraries                                           | `ON` / `OFF`                           | `OFF`                                                     |
 | `DEPS_INSTALL_DIR`    | no        | Define dependencies libraries install directory                                  | absolute path to an existing directory | `<antares_checkout_dir>/../rte-antares-deps-<build_type>` |
 | `USE_PRECOMPILED_EXT` | no        | This option must be set if you use wxWidget as precompiled external library      | `ON` / `OFF`                           | `OFF`                                                     |
@@ -91,3 +91,5 @@ Additional options for Windows:
   
 
 The final GUI file can be executed at `_build/ui/simulator/antares-X.Y-ui-simulator`
+
+[^1]: GUI support has been dropped in favor of [Antares Web](https://antares-web.readthedocs.io)
diff --git a/docs/build/4-Tests-dev.md → docs/developer-guide/4-Tests-dev.md b/docs/build/4-Tests-dev.md → docs/developer-guide/4-Tests-dev.md
@@ -57,6 +57,9 @@ In the future, CentOS 7 should be included as well.
 Every study contains a `check-config.json` file that configures the test. Here is its content.
 
 ### Contents
+[//]: # (TODO)
+_**This section is under construction**_
+
 #### name
 The name of the test. Not really important, and currently not used.
 
@@ -65,14 +68,12 @@ The list of checks that the test should conduct on the results.
 Contains one `output_compare` and one `integrity_compare` json objects.  
 
 ##### output-compare
-Either an empty json object (`{}`), or ?? TODO
 
 ##### integrity-compare
-Either `null`, or ?? TODO
 
 ### Full example
 ```json
-TODO
+
 ```
 
 ## Workflow

diff --git a/docs/build/4-Tests-user.md → docs/developer-guide/4-Tests-user.md b/docs/build/4-Tests-user.md → docs/developer-guide/4-Tests-user.md
diff --git a/docs/build/5-Installer-creation.md → docs/developer-guide/5-Installer-creation.md b/docs/build/5-Installer-creation.md → docs/developer-guide/5-Installer-creation.md
diff --git a/docs/CHANGELOG.md → docs/developer-guide/CHANGELOG.md b/docs/CHANGELOG.md → docs/developer-guide/CHANGELOG.md
diff --git a/docs/build/continuous-integration.md → ...developer-guide/continuous-integration.md b/docs/build/continuous-integration.md → ...developer-guide/continuous-integration.md
@@ -3,23 +3,16 @@
 
 Here is a description of workflows with their associated status.
 
-## Primary build & release workflows
+## Build & release workflows
 
-| OS               | .yml                            | Description                                                                             | Status                                               |
-|:-----------------|---------------------------------|-----------------------------------------------------------------------------------------|------------------------------------------------------|
-| Ubuntu           | `ubuntu.yml`                    | Builds Antares Simulator                                                                | [![Status][ubuntu_ci_svg]][ubuntu_ci_link]           |
-| Windows          | `windows-vcpkg.yml`             | Builds Antares Simulator                                                                | [![Status][windows_ci_svg]][windows_ci_link]         |
-| Centos7          | `centos7.yml`                   | Builds Antares Simulator                                                                | [![Status][centos_ci_svg]][centos_ci_link]           |
-| OracleLinux8     | `oracle8.yml`                   | Builds Antares Simulator                                                                | [![Status][oraclelinux_ci_svg]][oraclelinux_ci_link] |
-| -                | `build-userguide.yml`           | Generates PDF user guide from material in `docs/reference-guide` (uses Sphinx)          | [![Status][userguide_svg]][userguide_link]           |
-| All of the above | `new_release.yml`               | When a release is created, runs the aforementioned workflows and publishes their assets | [![Status][new_release_svg]][new_release_link]       |
-
-## Secondary build workflows
-
-| OS               | .yml                            | Description                                                                             | Status                                                     |
-|:-----------------|---------------------------------|-----------------------------------------------------------------------------------------|------------------------------------------------------------|
-| Ubuntu           | `ubuntu-system-deps-build.yml`  | Builds Antares Simulator's dependencies                                                 | [![Status][ubuntu_deps_build_svg]][ubuntu_deps_build_link] |
-| Centos7          | `centos7-system-deps-build.yml` | Builds Antares Simulator's dependencies                                                 | [![Status][centos_deps_build_svg]][centos_deps_build_link] |
+| OS               | .yml                  | Description                                                                             | Status                                               |
+|:-----------------|-----------------------|-----------------------------------------------------------------------------------------|------------------------------------------------------|
+| Ubuntu           | `ubuntu.yml`          | Builds Antares Simulator                                                                | [![Status][ubuntu_ci_svg]][ubuntu_ci_link]           |
+| Windows          | `windows-vcpkg.yml`   | Builds Antares Simulator                                                                | [![Status][windows_ci_svg]][windows_ci_link]         |
+| Centos7          | `centos7.yml`         | Builds Antares Simulator                                                                | [![Status][centos_ci_svg]][centos_ci_link]           |
+| OracleLinux8     | `oracle8.yml`         | Builds Antares Simulator                                                                | [![Status][oraclelinux_ci_svg]][oraclelinux_ci_link] |
+| -                | `build-userguide.yml` | Generates PDF user guide from material in `docs/user-guide` (uses Sphinx)               | [![Status][userguide_svg]][userguide_link]           |
+| All of the above | `new_release.yml`     | When a release is created, runs the aforementioned workflows and publishes their assets | [![Status][new_release_svg]][new_release_link]       |
 
 ## Additional workflows
 
@@ -39,18 +32,12 @@ Here is a description of workflows with their associated status.
 [ubuntu_ci_svg]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/workflows/Ubuntu%20CI%20(push%20and/or%20release)/badge.svg
 [ubuntu_ci_link]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/actions?query=workflow%3A"Ubuntu%20CI%20(push%20and/or%20release)"
 
-[ubuntu_deps_build_svg]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/workflows/Ubuntu%20CI%20(deps.%20compilation)/badge.svg
-[ubuntu_deps_build_link]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/actions?query=workflow%3A"Ubuntu%20CI%20(deps.%20compilation)"
-
 [windows_ci_only_svg]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/workflows/Windows%20CI%20(pre-compiled%20only)/badge.svg
 [windows_ci_only_link]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/actions?query=workflow%3A"Windows%20CI%20(pre-compiled%20only)"
 
 [windows_ci_svg]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/workflows/Windows%20CI%20(VCPKG%20and%20pre-compiled)/badge.svg
 [windows_ci_link]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/actions?query=workflow%3A"Windows%20CI%20(VCPKG%20and%20pre-compiled)"
 
-[centos_deps_build_svg]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/workflows/Centos7%20CI%20(deps.%20compilation)/badge.svg
-[centos_deps_build_link]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/actions?query=workflow%3A"Centos7%20CI%20(deps.%20compilation)"
-
 [centos_ci_svg]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/workflows/Centos7%20CI%20(push%20and/or%20release)/badge.svg
 [centos_ci_link]: https://github.com/AntaresSimulatorTeam/Antares_Simulator/actions?query=workflow%3A"Centos7%20CI%20(push%20and/or%20release)"
-Original file line number
+Diff line change
@@ Expand Up / @@ -3,7 +3,7 @@ hide: @@
      - toc
     ---
-    # Introduction
+    # Overview
     *ANTARES* is developed mainly in **C++**
@@ Expand Down @@