Docs: improve "Workflows" section for developers (ECP-WarpX#5525)

Suggestion for reviewers: Compare the preview of the new documentation available from the CI check `docs/readthedocs.org:warpx` with the existing documentation available online. Improve the [Workflows](https://warpx.readthedocs.io/en/latest/developers/workflows.html) documentation for developers, so far only the following sections: - "How to test the code" - "How to run the clang-tidy linter" To-do: - [x] Incorporate minimal checksum documentation in one single test section - [x] Add step-by-step guide on how to add new tests (enumerated list of steps)
EZoni · Jan 24, 2025 · 1d5f3c4 · 1d5f3c4
1 parent b9c31fd
commit 1d5f3c4
Show file tree

Hide file tree

Showing 9 changed files with 169 additions and 190 deletions.
diff --git a/Docs/source/developers/local_compile.rst → ...rce/developers/how_to_compile_locally.rst b/Docs/source/developers/local_compile.rst → ...rce/developers/how_to_compile_locally.rst
@@ -1,7 +1,7 @@
 .. _developers-local-compile:
 
-Fast, Local Compilation
-=======================
+How to compile locally and fast
+===============================
 
 For simplicity, WarpX :ref:`compilation with CMake <building-cmake>` by default downloads, configures and compiles compatible versions of :ref:`central dependencies <install-dependencies>` such as:
 

diff --git a/Docs/source/developers/how_to_guides.rst b/Docs/source/developers/how_to_guides.rst
@@ -0,0 +1,13 @@
+.. _development-howtoguides:
+
+How-to guides
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   how_to_profile
+   how_to_test
+   how_to_run_clang_tidy
+   how_to_compile_locally
+   how_to_write_the_docs
diff --git a/Docs/source/developers/profiling.rst → Docs/source/developers/how_to_profile.rst b/Docs/source/developers/profiling.rst → Docs/source/developers/how_to_profile.rst
@@ -1,7 +1,7 @@
 .. _developers-profiling:
 
-Profiling the Code
-==================
+How to profile the code
+=======================
 
 Profiling allows us to find the bottle-necks of the code as it is currently implemented.
 Bottle-necks are the parts of the code that may delay the simulation, making it more computationally expensive.

diff --git a/Docs/source/developers/how_to_run_clang_tidy.rst b/Docs/source/developers/how_to_run_clang_tidy.rst
@@ -0,0 +1,51 @@
+.. _developers-run_clang_tidy_locally:
+
+How to run the clang-tidy linter
+================================
+
+WarpX's CI tests include several checks performed with the `clang-tidy <https://clang.llvm.org/extra/clang-tidy/>`__ linter.
+The complete list of checks performed is defined in the ``.clang-tidy`` configuration file.
+
+.. dropdown:: clang-tidy configuration file
+   :color: light
+   :icon: info
+   :animate: fade-in-slide-down
+
+   .. literalinclude:: ../../../.clang-tidy
+      :language: yaml
+
+Under `Tools/Linter <https://github.com/ECP-WarpX/WarpX/blob/development/Tools/Linter>`__, the script ``runClangTidy.sh`` can be used to run the clang-tidy linter locally.
+
+.. dropdown:: clang-tidy local run script
+   :color: light
+   :icon: info
+   :animate: fade-in-slide-down
+
+   .. literalinclude:: ../../../Tools/Linter/runClangTidy.sh
+      :language: bash
+
+It is a prerequisite that WarpX is compiled following the instructions that you find in our :ref:`Users <install-cmake>` or :ref:`Developers <building-cmake>` sections.
+
+The script generates a wrapper to ensure that clang-tidy is only applied to WarpX source files and compiles WarpX in 1D, 2D, 3D, and RZ geometry, using such wrapper.
+
+By default WarpX is compiled in single precision with PSATD solver, QED module, QED table generator and embedded boundary in order to ensure broader coverage with the clang-tidy tool.
+
+Few optional environment variables can be set to tune the behavior of the script:
+
+* ``WARPX_TOOLS_LINTER_PARALLEL``: set the number of cores used for compilation;
+
+* ``CLANG``, ``CLANGXX``, and ``CLANGTIDY``: set the version of the compiler and the linter.
+
+For continuous integration we currently use clang version 15.0.0 and it is recommended to use this version locally as well.
+A newer version may find issues not currently covered by CI tests (checks are opt-in), while older versions may not find all the issues.
+
+Here's an example of how to run the script after setting the appropriate environment variables:
+
+.. code-block:: bash
+
+   export WARPX_TOOLS_LINTER_PARALLEL=12
+   export CLANG=clang-15
+   export CLANGXX=clang++-15
+   export CLANGTIDY=clang-tidy-15
+
+   ./Tools/Linter/runClangTidy.sh
diff --git a/Docs/source/developers/testing.rst → Docs/source/developers/how_to_test.rst b/Docs/source/developers/testing.rst → Docs/source/developers/how_to_test.rst
diff --git a/Docs/source/developers/documentation.rst → ...urce/developers/how_to_write_the_docs.rst b/Docs/source/developers/documentation.rst → ...urce/developers/how_to_write_the_docs.rst
@@ -1,7 +1,7 @@
 .. _developers-docs:
 
-Documentation
-=============
+How to write documentation
+==========================
 
 Doxygen documentation
 ---------------------

diff --git a/Docs/source/developers/run_clang_tidy_locally.rst b/Docs/source/developers/run_clang_tidy_locally.rst
diff --git a/Docs/source/developers/workflows.rst b/Docs/source/developers/workflows.rst
diff --git a/Docs/source/index.rst b/Docs/source/index.rst
@@ -126,7 +126,7 @@ Development
    developers/developers
    developers/doxygen
    developers/gnumake
-   developers/workflows
+   developers/how_to_guides
    developers/faq
 .. good to have in the future:
 ..   developers/repostructure