Update documentation

.pre-commit-config.yaml

@@ -8,6 +8,7 @@ repos:
   rev: v5.0.0
   hooks:
   - id: check-added-large-files
+    args: ['--maxkb=600']
   - id: check-case-conflict
   - id: check-executables-have-shebangs
   - id: check-merge-conflict

README.md

@@ -23,10 +23,6 @@ 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).
 
-> [!WARNING]
-> *remage* is still under heavy development. Users are advised to use a tagged
-> release for any workloads unrelated to remage development, if possible.
-
 ### Main features
 
 * Support for modern [Geant4](https://geant4.web.cern.ch), including

docs/CMakeLists.txt

@@ -34,9 +34,26 @@ set(SPHINX_SOURCE ${CMAKE_CURRENT_BINARY_DIR})
 set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/_build)
 set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
 
-set(SPHINX_SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/index.rst)
+# FIXME: the logic here to handle sources is not really clean, needs some more
+# serious thought! one important requirement is CMake being able to copy the
+# sources again if they change
+file(
+  GLOB SPHINX_SOURCES
+  RELATIVE ${CMAKE_CURRENT_SOURCE_DIR}
+  *.rst *.md)
+
 foreach(_file ${SPHINX_SOURCES})
-  configure_file(${_file} ${SPHINX_SOURCE} COPYONLY)
+  configure_file(${CMAKE_CURRENT_SOURCE_DIR}/${_file} ${SPHINX_SOURCE} COPYONLY)
+endforeach()
+
+file(
+  GLOB SPHINX_IMAGES
+  RELATIVE ${CMAKE_CURRENT_SOURCE_DIR}
+  img/*)
+
+file(MAKE_DIRECTORY ${SPHINX_SOURCE}/img)
+foreach(_file ${SPHINX_IMAGES})
+  configure_file(${CMAKE_CURRENT_SOURCE_DIR}/${_file} ${SPHINX_SOURCE}/img COPYONLY)
 endforeach()
 
 configure_file(${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in ${SPHINX_SOURCE}/conf.py @ONLY)
@@ -46,7 +63,7 @@ add_custom_command(
   COMMAND ${SPHINX_EXECUTABLE} -b html -Dbreathe_projects.remage=${DOXYGEN_OUTPUT_DIR}/xml
           ${SPHINX_SOURCE} ${SPHINX_BUILD}
   WORKING_DIRECTORY ${SPHINX_SOURCE}
-  DEPENDS ${SPHINX_SOURCES} ${DOXYGEN_INDEX_FILE}
+  DEPENDS ${SPHINX_SOURCES} ${SPHINX_IMAGES} ${DOXYGEN_INDEX_FILE}
   MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py
   ${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in
   COMMENT "Generating Sphinx docs")

docs/conf.py.in

@@ -20,6 +20,7 @@ extensions = [
     "sphinx.ext.intersphinx",
     "sphinx.ext.graphviz",
     "sphinx_copybutton",
+    "sphinx_togglebutton",
     "sphinx_inline_tabs",
     "exhale",
     "breathe",
@@ -38,6 +39,8 @@ exhale_args = {
 
 breathe_projects = {}
 
+myst_enable_extensions = ["colon_fence"]
+
 if on_rtd:
     # assume build has been prepared in .readthedocs.yml
     breathe_projects["remage"] = "_doxygen/xml"

docs/developer.rst

@@ -96,6 +96,18 @@ following:
   other) must be provided as separate pages in ``docs/`` and linked in the
   table of contents.
 
+To generate documentation locally, run
+
+.. code-block:: console
+
+  $ cd remage/build/
+  $ cmake .. -DRMG_BUILD_DOCS=ON
+  $ make sphinx
+
+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
 ^^^^^^^^^^^^^^^^^^^^^
 

docs/environment.yml

@@ -15,4 +15,5 @@ dependencies:
   - setuptools-scm
   - sphinx
   - sphinx-copybutton
+  - sphinx-togglebutton
   - sphinx-inline-tabs

docs/index.rst

@@ -3,55 +3,14 @@ remage
 
 |remage| is a modern C++ simulation framework for germanium experiments.
 
-Pre-built binaries
-------------------
-
-The recommended and fastest way of running |remage| is through pre-built
-software containers. Stable releases are regularly made available `on Docker
-Hub <https://hub.docker.com/repository/docker/gipert/remage>`_. To obtain and
-run the latest just do:
-
-.. code-block:: console
-
-   $ docker run gipert/remage --help # just prints a help message
-
-If you prefer `Apptainer <https://apptainer.org/>`_, you can easily generate an image locally:
-
-.. code-block:: console
-
-  $ apptainer build remage_latest.sif docker://gipert/remage:latest
-  $ apptainer run remage_latest.sif --help
-
-If containers do not work for you, see the next section to learn how to build
-and install from source.
-
-Building from source
---------------------
-
-In preparation for the actual build, users are required to obtain some
-dependencies.
-
-.. include:: _dependencies.rst
-
-Building
-^^^^^^^^
-
-The build system is based on CMake:
-
-.. code-block:: console
-
-   $ git clone https://github.com/legend-exp/remage
-   $ cd remage
-   $ mkdir build && cd build
-   $ cmake -DCMAKE_INSTALL_PREFIX=<optional prefix> ..
-   $ make install
-
 Quick start
 -----------
 
+The installation process is documented in :doc:`install`.
+
 .. warning::
    A proper user guide is not available yet. In the meanwhile, users can have a
-   look at the `examples
+   look at the :doc:`tutorial` or the provided `examples
    <https://github.com/legend-exp/remage/tree/main/examples>`_.
 
 In the simplest application, the user can simulate in an existing GDML geometry
@@ -98,6 +57,8 @@ Next steps
 .. toctree::
     :maxdepth: 2
 
+    install
+    tutorial
     Geant4 command interface <rmg-commands>
     Output structure & LH5 output <output>
 

docs/install.rst

@@ -0,0 +1,47 @@
+Installation
+============
+
+Pre-built binaries
+------------------
+
+The recommended and fastest way of running |remage| is through pre-built
+software containers. Stable releases are regularly made available `on Docker
+Hub <https://hub.docker.com/repository/docker/legendexp/remage>`_. To obtain and
+run the latest just do:
+
+.. code-block:: console
+
+   $ docker run legendexp/remage:latest --help # just prints a help message
+
+If you prefer `Apptainer <https://apptainer.org/>`_, you can easily generate an image locally:
+
+.. code-block:: console
+
+  $ apptainer build remage_latest.sif docker://legendexp/remage:latest
+  $ apptainer run remage_latest.sif --help
+
+If containers do not work for you, see the next section to learn how to build
+and install from source.
+
+Building from source
+--------------------
+
+In preparation for the actual build, users are required to obtain some
+dependencies.
+
+.. include:: _dependencies.rst
+
+Building
+^^^^^^^^
+
+The build system is based on CMake:
+
+.. code-block:: console
+
+   $ git clone https://github.com/legend-exp/remage
+   $ cd remage
+   $ mkdir build && cd build
+   $ cmake -DCMAKE_INSTALL_PREFIX=<optional prefix> ..
+   $ make install
+
+.. |remage| replace:: *remage*