docs: add simple devguide

docs/_dependencies.rst

@@ -0,0 +1,44 @@
+Required dependencies
+^^^^^^^^^^^^^^^^^^^^^
+
+- `CMake <https://cmake.org>`_ 3.12 or higher
+- |geant4|_ 11.0.3 or higher
+
+Optional dependencies
+^^^^^^^^^^^^^^^^^^^^^
+
+- |geant4|_ support for:
+
+  - HDF5 object persistency
+  - Multithreading
+  - GDML geometry description
+
+- |root|_ 6.06 or higher
+- |bxdecay0|_ 1.0.10 or higher
+- |hdf5|_ C++ support for LH5 object persistency
+
+.. note::
+
+   Pre-built Docker container images with all necessary dependencies are available `on
+   Docker Hub <https://hub.docker.com/repository/docker/gipert/remage-base>`_.
+
+.. note::
+
+   Apptainer images can be easily generated with, e.g.:
+
+   .. code-block:: console
+
+      $ [sudo] apptainer build remage-base_latest.sif docker://gipert/remage-base:latest
+
+   For more details, have a look at `the documentation
+   <https://apptainer.org/docs/user/main/build_a_container.html>`_.
+
+
+.. |geant4| replace:: Geant4
+.. _geant4: https://geant4.web.cern.ch
+.. |root| replace:: ROOT
+.. _root: https://root.cern.ch
+.. |bxdecay0| replace:: BxDecay0
+.. _bxdecay0: https://github.com/BxCppDev/bxdecay0
+.. |hdf5| replace:: HDF5
+.. _hdf5: https://www.hdfgroup.org/solutions/hdf5

docs/developer.rst

@@ -0,0 +1,128 @@
+Developer's guide
+=================
+
+The following rules and conventions have been established for the package
+development and are enforced throughout the entire code base. Merge requests
+that do not comply to the following directives will be rejected.
+
+To start developing |remage|, fork the remote repository to your personal
+GitHub account (see `About Forks
+<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks>`_).
+If you have not set up your ssh keys on the computer you will be working on,
+please follow `GitHub's instructions
+<https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent>`_.
+Once you have your own fork, you can clone it via
+(replace "yourusername" with your GitHub username):
+
+.. code-block:: console
+
+  $ git clone [email protected]:yourusername/remage.git
+
+
+Installing dependencies
+-----------------------
+
+.. include:: _dependencies.rst
+
+Building
+--------
+
+|remage| currently only supports an out-of-tree build using CMake. To build and
+install remage from a source checkout, run:
+
+.. code-block:: console
+
+   $ cd remage
+   $ mkdir build && cd build
+   $ cmake -DCMAKE_INSTALL_PREFIX=<optional prefix> ..
+   $ make install
+
+Code style
+----------
+
+A set of `pre-commit <https://pre-commit.com>`_ hooks is configured to make
+sure that |remage| coherently follows standard coding style conventions.
+The pre-commit tool is able to identify common style problems and automatically
+fix them, wherever possible. Configured hooks are listed in the
+``.pre-commit-config.yaml`` file at the project root folder. They are run
+remotely on the GitHub repository through the `pre-commit bot
+<https://pre-commit.ci>`_, but should also be run locally before submitting a
+pull request:
+
+.. code-block:: console
+
+  $ cd remage
+  $ pip install pre-commit
+  $ pre-commit run --all-files  # analyse the source code and fix it wherever possible
+  $ pre-commit install          # install a Git pre-commit hook (optional, but strongly recommended)
+
+Testing
+-------
+
+* The |remage| test suite is available below ``tests/``. We use `ctest
+  <https://cmake.org/cmake/help/book/mastering-cmake/chapter/Testing%20With%20CMake%20and%20CTest.html>`_
+  to run tests and analyze their output.
+
+* Tests are automatically run for every push event and pull request to the
+  remote Git repository on a remote server (currently handled by GitHub
+  actions). All pull request typically have to pass all tests before being
+  merged. Running the test suite is simple:
+
+  .. code-block:: console
+
+    $ cd remage/build/
+    $ make
+    $ ctest
+
+  .. note ::
+
+    Some tests are known to be flaky, especially with older Geant4 version
+    branches.
+
+Documentation
+-------------
+
+We adopt best practices in writing and maintaining |remage|'s
+documentation. When contributing to the project, make sure to implement the
+following:
+
+* Documentation should be exclusively available on the Project website
+  `remage.readthedocs.io <https://remage.readthedocs.io>`_. No READMEs,
+  GitHub/LEGEND wiki pages should be written.
+* Pull request authors are required to provide sufficient documentation for
+  every proposed change or addition.
+* General guides, comprehensive tutorials or other high-level documentation
+  (e.g. referring to how separate parts of the code interact between each
+  other) must be provided as separate pages in ``docs/`` and linked in the
+  table of contents.
+
+Writing documentation
+^^^^^^^^^^^^^^^^^^^^^
+
+Documentation source files must formatted in reStructuredText (reST). A
+reference format specification is available on the `Sphinx reST usage guide
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_.
+
+Automatic command reference generation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you change the Geant macro command-based interface in a pull request, please
+regenerate the documentation file :doc:`online command-reference <rmg-commands>`
+before committing those changes:
+
+.. code-block:: console
+
+    $ cd remage/build/
+    $ make remage-doc-dump
+
+The generated documentation file is also tracked using git, and not automatically
+rebuilt when the documentation is built, i.e. for ReadTheDocs.
+
+Manually changing the checked-in file ``rmg-commands.rst`` is neither required nor
+possible, all changes will be overwritten by the next automatic update.
+
+The GitHub CI jobs will only check if the command-reference file is up-to-date
+with the actual source code for each pull reuquest or push, but it will *not*
+update the documentation automatically.
+
+.. |remage| replace:: *remage*

docs/index.rst

@@ -9,40 +9,7 @@ Building the project
 Users are required to build the project themselves, since no official binaries
 are distributed, at the moment.
 
-Required dependencies
-^^^^^^^^^^^^^^^^^^^^^
-
-- `CMake <https://cmake.org>`_ 3.12 or higher
-- |geant4|_ 11.0.3 or higher
-
-Optional dependencies
-^^^^^^^^^^^^^^^^^^^^^
-
-- |geant4|_ support for:
-
-  - HDF5 object persistency
-  - Multithreading
-  - GDML geometry description
-
-- |root|_ 6.06 or higher
-- |bxdecay0|_ 1.0.10 or higher
-- |hdf5|_ C++ support for LH5 object persistency
-
-.. note::
-
-   Pre-built Docker container images with all necessary dependencies are available `on
-   Docker Hub <https://hub.docker.com/repository/docker/gipert/remage-base>`_.
-
-.. note::
-
-   Apptainer images can be easily generated with, e.g.:
-
-   .. code-block:: console
-
-      $ [sudo] apptainer build remage-base_latest.sif docker://gipert/remage-base:latest
-
-   For more details, have a look at `the documentation
-   <https://apptainer.org/docs/user/main/build_a_container.html>`_.
+.. include:: _dependencies.rst
 
 Building
 ^^^^^^^^
@@ -114,18 +81,11 @@ Next steps
     :maxdepth: 1
     :caption: Development
 
+    Developer's guide <developer>
     api/index
     Good ol' Doxygen <https://remage.readthedocs.io/en/latest/doxygen/annotated.html>
     Source Code <https://github.com/legend-exp/remage>
     License <https://github.com/legend-exp/remage/blob/main/LICENSE>
     Citation <https://doi.org/10.5281/zenodo.11115662>
 
 .. |remage| replace:: *remage*
-.. |geant4| replace:: Geant4
-.. _geant4: https://geant4.web.cern.ch
-.. |root| replace:: ROOT
-.. _root: https://root.cern.ch
-.. |bxdecay0| replace:: BxDecay0
-.. _bxdecay0: https://github.com/BxCppDev/bxdecay0
-.. |hdf5| replace:: HDF5
-.. _hdf5: https://www.hdfgroup.org/solutions/hdf5