Merge pull request #202 from legend-exp/docs

.github/CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# Contributing
+
+Before opening a PR:
+
+- make sure to follow our code style conventions
+- run pre-commit and fix all the issues
+- add documentation, either as code docstrings or as manual pages
+- if unsure about the docs format, build the documentation and check the result
+- add tests for your new feature
+- run tests and check if they all pass
+- if adding a new macro command, update the macro command reference page
+- prepare a coherent and tidy commit history (with e.g. `git rebase -i`)
+
+After the CI has run:
+
+- fix all reported problems, if any
+- navigate to the ReadTheDocs documentation build (linked in the GitHub
+  actions report for the PR) and check that the docs are properly rendered
+- download and check the test outputs from the GitHub actions interface
+
+For more details, refer to the [developer's guide](https://remage.readthedocs.io/en/stable/developer.html).

README.md

@@ -9,32 +9,44 @@ Simulation framework for germanium detector experiments
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
 ![GitHub issues](https://img.shields.io/github/issues/legend-exp/remage?logo=github)
 ![GitHub pull requests](https://img.shields.io/github/issues-pr/legend-exp/remage?logo=github)
-![License](https://img.shields.io/github/license/legend-exp/remage)
 [![Read the Docs](https://img.shields.io/readthedocs/remage?logo=readthedocs)](https://remage.readthedocs.io)
+[![Docker Hub](https://img.shields.io/badge/Docker-Hub-blue?logo=docker)](https://hub.docker.com/r/legendexp/remage)
+![License](https://img.shields.io/github/license/legend-exp/remage)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.11115662.svg)](https://doi.org/10.5281/zenodo.11115662)
 
 <br/>
 
-The *remage* project aims to provide a modern Geant4-based C++ library to
-efficiently simulate particle physics processes in typical germanium detector
-experiments. The library is setup-agnostic, and therefore the only mandatory
-user action is to provide a geometrical implementation of the experimental
-setup (supported specification languages are C++, GDML and more). The user can
-then benefit from a predefined set of tools to perform common actions (physics
-generators, standard output classes, etc).
+The *remage* project aims to deliver a modern Geant4-based C++ library designed
+for efficient simulation of particle physics processes in typical germanium
+detector experiments. The library is setup-agnostic, requiring users only to
+define the experimental setup's geometry. Supported specification languages
+include C++, GDML, and others. Once the geometry is provided, users can access
+a comprehensive suite of tools for common tasks, such as physics generation and
+standard output handling.
+
+Get started with our [documentation pages](https://remage.readthedocs.io)!
 
 ### Main features
 
-* Support for modern [Geant4](https://geant4.web.cern.ch), including
-    * Multithreading
-    * [VecGeom](https://gitlab.cern.ch/VecGeom/VecGeom) support for vectorized
-      solids
-    * [GDML](https://gdml.web.cern.ch/GDML) support
-    * Multiple output file formats ([ROOT](https://root.cern.ch),
-      [HDF5](https://www.hdfgroup.org/solutions/hdf5)...)
+* Low entry barrier: Most simulations can be executed directly using the
+  `remage` executable and a macro file, eliminating the need to write or
+  compile C++ code.
+* Various pre-compiled *remage* versions available on
+  [Docker Hub](https://hub.docker.com/repository/docker/legendexp/remage)
+* Support for modern [Geant4](https://geant4.web.cern.ch), including:
+  * Multithreading
+  * [GDML](https://gdml.web.cern.ch/GDML) support
+  * Multiple output file formats ([ROOT](https://root.cern.ch),
+    [HDF5](https://www.hdfgroup.org/solutions/hdf5)...)
+* [LEGEND HDF5 (LH5)](https://legend-exp.github.io/legend-data-format-specs/dev/hdf5/)
+  output format
 * Fast third-party cosmic muon generator (through
   [EcoMug](https://doi.org/10.1016/j.nima.2021.165732))
+* Support for external generators:
+  * [MUSUN](https://doi.org/10.1016/j.cpc.2008.10.013)
+  * [MAURINA](https://doi.org/10.1140/epja/s10050-024-01336-0)
 * Third-party double-beta decay generator (through
   [bxdecay0](https://github.com/BxCppDev/bxdecay0))
-* Advanced vertex confinement on physical volumes, geometrical solids, surfaces and intersections
-* Common output schemes for HPGe and optical detectors
+* Advanced vertex confinement on physical volumes, geometrical solids, surfaces
+  and intersections
+* Sensible output schemes for HPGe and optical detectors

docs/developer.md

@@ -67,10 +67,11 @@ $ make
 $ ctest
 ```
 
-:::{note}
-Some tests are known to be flaky, especially with older Geant4 version
-branches.
-:::
+If tests produce output files with an extension that contains an `.output`
+sub-extension, they will be automatically uploaded to GitHub as part of a
+tarball. This can be downloaded and inspected from the GitHub actions run page:
+navigate to "Actions", select the CI run of interest, scroll to the bottom of
+the page.
 
 Cheatsheet:
 ```console
@@ -79,11 +80,6 @@ $ ctest -L vis # run only tests with label "vis"
 $ ctest -R basics-mt/print-volumes.mac # run only this test
 ```
 
-`vis` tests are currently not run in CI, since there is no graphical
-environment available. Moreover, they won't be marked as "failed" (but rather
-"skipped") if they fail due to the same reason. In case you want to run them
-locally, make sure there is support for graphics.
-
 If you want to open a fanci UI to check the output of `vis` tests, you may
 achieve it by:
 
@@ -104,10 +100,16 @@ following:
   GitHub/LEGEND wiki pages should be written.
 - Pull request authors are required to provide sufficient documentation for
   every proposed change or addition.
+- Documentation for classes/methods etc. should be provided in the same source
+  file, as Doxygen-formatted comments (see e.g. [this
+  guide](https://www.doxygen.nl/manual/docblocks.html)). They will be
+  automatically added to the API documentation section on ReadTheDocs.
 - 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.
+  table of contents. These 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).
 
 To generate documentation locally, run
 
@@ -121,12 +123,6 @@ You'll need a Doxygen installation and Python software dependencies specified
 in `docs/environment.yml`. The generated documentation can be viewed by
 pointing your browser to `docs/_build/index.html`.
 
-### 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