From 5189eb6ed5088178a49c832e810eea65b12d25f0 Mon Sep 17 00:00:00 2001
From: Luigi Pertoldi <luigi.pertoldi@protonmail.com>
Date: Sat, 12 Aug 2023 14:18:01 +0200
Subject: [PATCH] Improve docs landing page

---
 .gitignore      |   3 ++
 CMakeLists.txt  |  10 ++++-
 docs/conf.py.in |   1 -
 docs/index.rst  | 109 ++++++++++++++++++++++++++++++++++++++++++++++--
 4 files changed, 117 insertions(+), 6 deletions(-)

diff --git a/.gitignore b/.gitignore
index 286fd5b..f5c4ebc 100644
--- a/.gitignore
+++ b/.gitignore
@@ -25,3 +25,6 @@ compile_commands.json
 *.swo
 .mypy_cache
 __pycache__
+
+# python
+.venv
diff --git a/CMakeLists.txt b/CMakeLists.txt
index b623f28..69ab077 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -187,4 +187,12 @@ create_mage_toolchain()
 include(DependencyGraph)
 gen_dep_graph(pdf)
 
-message(STATUS "remage install prefix set to ${CMAKE_INSTALL_PREFIX}")
+message(STATUS "")
+message(STATUS "WWW: remage install prefix set to ${CMAKE_INSTALL_PREFIX}")
+message(STATUS "WWW: if the install location is non-standard, don't forget to")
+message(STATUS "WWW: update the relevant environment variables:")
+message(STATUS "WWW:   export PATH=${CMAKE_INSTALL_PREFIX}/bin:$PATH")
+message(STATUS "WWW:   export LD_LIBRARY_PATH=${CMAKE_INSTALL_PREFIX}/lib:$LD_LIBRARY_PATH")
+message(
+  STATUS "WWW:   export CMAKE_PREFIX_PATH=${CMAKE_INSTALL_PREFIX}/lib/cmake:$CMAKE_PREFIX_PATH")
+message(STATUS "")
diff --git a/docs/conf.py.in b/docs/conf.py.in
index 6743fc2..a2ec048 100644
--- a/docs/conf.py.in
+++ b/docs/conf.py.in
@@ -57,7 +57,6 @@ else:
     warnings_filter_config = "@PROJECT_SOURCE_DIR@/docs/known-warnings.txt"
 
 breathe_default_project = "remage"
-highlight_language = "c++"
 html_extra_path = ["extra"]
 
 # Furo theme
diff --git a/docs/index.rst b/docs/index.rst
index 8d82427..e5d3777 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,11 +1,112 @@
-Welcome to remage's documentation!
-==================================
+remage
+======
 
-*Coming soon...*
+|remage| is a modern C++ simulation framework for germanium experiments.
 
-* `Good ol' Doxygen docs <doxygen/annotated.html>`_
+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
+
+.. 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>`_.
+
+Building
+^^^^^^^^
+
+.. 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
+
+Usage
+-----
+
+.. warning::
+   A proper user guide is not available yet. In the meanwhile, users can have a
+   look at the `examples
+   <https://github.com/legend-exp/remage/tree/main/examples>`_.
+
+In the simplest application, the user can simulate in an existing GDML geometry
+through the ``remage`` executable:
+
+.. code-block:: console
+
+   $ remage --help
+   remage: simulation framework for germanium experiments
+   Usage: src/remage [OPTIONS] [macros...]
+
+   Positionals:
+     macros TEXT ...             Macro files
+
+   Options:
+     -h,--help                   Print this help message and exit
+     -q                          Print only warnings and errors
+     -v [0]                      Verbosity
+     -l,--log-level ENUM         Logging level
+     -i,--interactive            Run in interactive mode
+     -t,--threads INT            Number of threads
+     -g,--gdml-files TEXT ...    GDML files
+
+Advanced applications can extend |remage| and link against ``libremage`` with the
+usual CMake syntax:
+
+.. code-block:: cmake
+
+    project(myapp)
+    find_package(remage)
+    # add_library(myapp ...)
+    # add_executable(myapp ...)
+    target_link_libraries(myapp PRIVATE RMG::remage)
+
+Next steps
+----------
 
 .. toctree::
     :maxdepth: 2
 
     api/index
+    Good ol' Doxygen <https://remage.readthedocs.io/en/latest/doxygen/annotated.html>
+
+.. |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