diff --git a/docs/_dependencies.rst b/docs/_dependencies.rst new file mode 100644 index 0000000..62225d4 --- /dev/null +++ b/docs/_dependencies.rst @@ -0,0 +1,44 @@ +Required dependencies +^^^^^^^^^^^^^^^^^^^^^ + +- `CMake `_ 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 `_. + +.. 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 + `_. + + +.. |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 diff --git a/docs/developer.rst b/docs/developer.rst new file mode 100644 index 0000000..5417ba2 --- /dev/null +++ b/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 +`_). +If you have not set up your ssh keys on the computer you will be working on, +please follow `GitHub's instructions +`_. +Once you have your own fork, you can clone it via +(replace "yourusername" with your GitHub username): + +.. code-block:: console + + $ git clone git@github.com: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= .. + $ make install + +Code style +---------- + +A set of `pre-commit `_ 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 +`_, 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 + `_ + 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 `_. 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 +`_. + +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 ` +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* diff --git a/docs/index.rst b/docs/index.rst index 28e53c5..4546c6d 100644 --- a/docs/index.rst +++ b/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 `_ 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 `_. - -.. 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 - `_. +.. include:: _dependencies.rst Building ^^^^^^^^ @@ -114,6 +81,7 @@ Next steps :maxdepth: 1 :caption: Development + Developer's guide api/index Good ol' Doxygen Source Code @@ -121,11 +89,3 @@ Next steps Citation .. |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