fix external links and other minor issues with the documentation

Author: MilanKlausz

doc/source/about.rst

@@ -4,9 +4,8 @@ About
 
 .. include:: cite.rst
 
-Please report any bugs, problems or feature requests related to
-simplebuild-dgcode in the issue tracker at:
-https://github.com/mctools/simplebuild-dgcode/issues.
+Please report any bugs, problems or feature requests related to dgcode in the
+issue tracker at: https://github.com/mctools/simplebuild-dgcode/issues.
 
 .. _sbhistory:
 

doc/source/cite.rst

@@ -3,12 +3,12 @@
 
   | **For dgcode:**
   | T Kittelmann et al 2014 J. Phys.: Conf. Ser. 513 022017
-  | `DOI 10.1088/1742-6596/513/2/022017 <https://doi.org/10.1088/1742-6596/513/2/022017>`_
+  | `DOI 10.1088/1742-6596/513/2/022017 <https://doi.org/10.1088/1742-6596/513/2/022017>`__
   | K Kanaki, T Kittelmann, et al 2018 Physica B, Condens. Matter 551 386–389
-  | `DOI 10.1016/j.physb.2018.03.025 <https://doi.org/10.1016/j.physb.2018.03.025>`_
+  | `DOI 10.1016/j.physb.2018.03.025 <https://doi.org/10.1016/j.physb.2018.03.025>`__
   | **For NCrystal:**
   | X.-X. Cai and T. Kittelmann, Comp. Phys. Commun 246 (2020) 106851,
-  | `DOI 10.1016/j.cpc.2019.07.015 <https://doi.org/10.1016/j.cpc.2019.07.015>`_
+  | `DOI 10.1016/j.cpc.2019.07.015 <https://doi.org/10.1016/j.cpc.2019.07.015>`__
   | **For MCPL**:
   | T. Kittelmann, et al., Comp. Phys. Commun 218 (2017) 17-42
-  | `DOI 10.1016/j.cpc.2017.04.012 <https://doi.org/10.1016/j.cpc.2017.04.012>`_
+  | `DOI 10.1016/j.cpc.2017.04.012 <https://doi.org/10.1016/j.cpc.2017.04.012>`__

doc/source/griff.rst

@@ -13,8 +13,8 @@ optimised for easy, fast and reliable analyses from either C++ or Python of
 low-multiplicity physics, but supports filtering for scenarios involving higher
 multiplicities or statistics. No dedicated publication for Griff exists at this
 point in time, but it was presented in `doi:10.1088/1742-6596/513/2/022017
-<http://dx.doi.org/10.1088/1742-6596/513/2/022017>`_ which should so far be used
-as the main reference.
+<http://dx.doi.org/10.1088/1742-6596/513/2/022017>`__ which should so far be
+used as the main reference.
 
 Data contents
 -------------

doc/source/index.rst

@@ -3,7 +3,7 @@ Welcome to the dgcode documentation!
 ************************************
 
 Welcome to the documentation of "dgcode", a set of `simplebuild
-<https://mctools.github.io/simplebuild>`_ packages implementing a Geant4-based
+<https://mctools.github.io/simplebuild>`__ packages implementing a Geant4-based
 simulation framework. It originated in the Detector Group at the European
 Spallation Source ERIC, and is primarily intended for usage for simulation of
 thermal neutron detectors and related projects.

doc/source/install.rst

@@ -57,7 +57,7 @@ Alternatives for experts
 The conda recipe above is intended to give a self-contained and reproducible
 environment with not only dgcode itself, but also any required tools like
 `simplebuild
-<https://mctools.github.io/simplebuild>`_, a Python interpreter, and
+<https://mctools.github.io/simplebuild>`__, a Python interpreter, and
 all the necessary build tools. For special advanced use cases, experts might
 simply want to add the code itself into an environment where they otherwise have
 ensured that all of these third-party tools are already available. In such a

doc/source/intro.rst

@@ -68,9 +68,9 @@ Features
 
 * Post-simulation analysis can be done as desired, and might for instance
   include a Griff analysis written in C++, which outputs histogram data in
-  :ref:`SimpleHists<sbsimplehists>` files, usually followed by a final
+  :ref:`SimpleHists <sbsimplehists>` files, usually followed by a final
   statistical analysis and plot-production in Python, where all the usual
-  tools (e.g. `Matplotlib<https://matplotlib.org/>`__ and
+  tools (e.g. `Matplotlib <https://matplotlib.org/>`__ and
   `SciPy <https://scipy.org/>`__) are available.
 
 * Due in particular to being based on `simplebuild

doc/source/license.rst

@@ -3,7 +3,7 @@ License
 *******
 
 ``simplebuild-dgcode`` is licensed under the `Apache-2.0 License
-<https://www.apache.org/licenses/LICENSE-2.0>`_.
+<https://www.apache.org/licenses/LICENSE-2.0>`__.
 
 .. include:: ../../LICENSE
   :literal:

doc/source/matcookbook.rst

@@ -72,7 +72,7 @@ case. Instead, one can currently resort to a few different strategies:
 
 - Use the ``G4_STAINLESS-STEEL`` material, which is a structure-less material
   with a particular composition defined in `Geant4's database
-  <https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/Appendix/materialNames.html>`_.
+  <https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/Appendix/materialNames.html>`__.
 - Use either ``stdlib::Fe_sg229_Iron-alpha.ncmat`` or
   ``stdlib::Fe_sg225_Iron-gamma.ncmat``, and the
   `atomdb <https://github.com/mctools/ncrystal/wiki/CfgRefDoc>`__ keyword of
@@ -257,7 +257,7 @@ density when using these to model a particular component. You can also read the
 notes for a particular material by a command like ``nctool --extract
 stdlib::Polystyrene_C8H8.ncmat | less`` (or simply find and click on the
 material on the `NCrystal data library page
-<https://github.com/mctools/ncrystal/wiki/Data-library>`_.
+<https://github.com/mctools/ncrystal/wiki/Data-library>`__.
 
 .. list-table::
    :header-rows: 1
@@ -446,8 +446,8 @@ aluminium atoms are actually randomly switched with chromium atoms.
 In general the NCrystal cfg-string syntax for defining a multi-phase material is
 ``phases<FRAC1*CFG1&..&FRACN*CFGN>[;COMMONCFG]``. Here, ``FRAC1`` is the
 fraction of phase 1, which is defined by the NCrystal cfg-string ``CFG1``, and
-so forth. The indicated fractions are assumed to be volume fractions, and must
-sum to 1, and ``COMMONCFG`` contains cfg-parameters applied to all phases
+so forth. The indicated fractions are assumed to be "by-volume" fractions, and
+must sum to 1, and ``COMMONCFG`` contains cfg-parameters applied to all phases
 (e.g. if ``COMMONCFG`` is ``;temp=200K``, all phases would change their
 temperature -- which in the particular case of temperature is quite sensible).
 
@@ -536,7 +536,7 @@ https://github.com/mctools/ncrystal-notebooks.
 
   | **If you use NCrystal to model single crystals, please cite:**
   | T. Kittelmann and X.-X. Cai, Comp. Phys. Commun 267 (2021) 108082,
-  | `DOI 10.1016/j.cpc.2021.108082 <https://doi.org/10.1016/j.cpc.2021.108082>`_
+  | `DOI 10.1016/j.cpc.2021.108082 <https://doi.org/10.1016/j.cpc.2021.108082>`__
 
 .. _sbmatpg:
 
@@ -586,7 +586,7 @@ it. The example below shows this in practice:
 
   | **If you use NCrystal to model pyrolitic graphite, please cite:**
   | T. Kittelmann and X.-X. Cai, Comp. Phys. Commun 267 (2021) 108082,
-  | `DOI 10.1016/j.cpc.2021.108082 <https://doi.org/10.1016/j.cpc.2021.108082>`_
+  | `DOI 10.1016/j.cpc.2021.108082 <https://doi.org/10.1016/j.cpc.2021.108082>`__
 
 Other materials
 ---------------

doc/source/matdef.rst

@@ -12,7 +12,7 @@ as the "NamedMaterial" mechanism, has several advantages:
 #. Defining materials is easier.
 #. Materials can be easily modified from command line or Python code.
 #. It integrates directly with how materials are defined in `NCrystal
-   <https://github.com/mctools/ncrystal/wiki>`_, allowing direct usage of these
+   <https://github.com/mctools/ncrystal/wiki>`__, allowing direct usage of these
    high-fidelity materials, and exposing all features of NCrystal directly.
 
 In the following, we will provide a few :ref:`general remarks <sbmatgeneral>`
@@ -26,15 +26,15 @@ General remarks
 ---------------
 
 The strings defining most materials in typical dgcode projects will actually be
-the same strings that are used with `NCrystal (aka "NCrystal cfg-strings)
-<https://github.com/mctools/ncrystal/wiki/Using-NCrystal#uniform-material-configuration-syntax>`_,
-so you might wish to consult the NCrystal documentation for those. Most
-of the entries in the :ref:`cookbook <sbmatcookbook>` are indeed such NCrystal
-cfg-strings.
+the same strings that are used with NCrystal (aka "NCrystal cfg-strings),
+so you might wish to consult the `NCrystal documentation
+<https://github.com/mctools/ncrystal/wiki/Using-NCrystal#uniform-material-configuration-syntax>`__
+for those. Most of the entries in the :ref:`cookbook <sbmatcookbook>` are
+indeed such NCrystal cfg-strings.
 
 On that note, be aware that outside the :ref:`cookbook <sbmatcookbook>` you
 can look for specific NCrystal materials both online in the `NCrystal data
-library page <https://github.com/mctools/ncrystal/wiki/Data-library>`_, or in
+library page <https://github.com/mctools/ncrystal/wiki/Data-library>`__, or in
 your terminal via the ``nctool`` command by invoking ``nctool
 --browse``. Combined with the unix ``grep`` command, you can use this for a
 quick-and-dirty material search in the terminal. As an example, searching for
@@ -70,7 +70,7 @@ directory). For this reason, most of the examples in the :ref:`cookbook
 
 In addition to NCrystal materials, you can also use any material from Geant4's
 own `built-in database of elements and NIST compounds
-<https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/Appendix/materialNames.html>`_,
+<https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/Appendix/materialNames.html>`__,
 and even override their temperature or density, using dedicated keywords
 ``temp_kelvin`` (:math:`\mathrm{K}`), ``density_gcm3``
 (:math:`\mathrm{g}/\mathrm{cm}^3`), ``density_kgm3``
@@ -112,7 +112,7 @@ Inspect via NCrystal utilities
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The material definitions which are also `NCrystal cfg-strings
-<https://github.com/mctools/ncrystal/wiki/Using-NCrystal#uniform-material-configuration-syntax>`_,
+<https://github.com/mctools/ncrystal/wiki/Using-NCrystal#uniform-material-configuration-syntax>`__,
 can be investigated with NCrystal tools. The most easily used of these is the
 command line tool ``nctool``, and the usage is very simple. First of all,
 detailed thermal neutron cross sections and sample neutron scattering

doc/source/newsimproject.rst

@@ -29,7 +29,7 @@ build everything afterwards with ``sb`` (that might take a few minutes):
 So assuming we want a project to investigate the properties of a new amazing
 detector technology, named "tricorder", we then proceed by using the
 ``dgcode_newsimproject`` command (please try to use `CamelCasing
-<https://en.wikipedia.org/wiki/Camel_case>`_ for project names):
+<https://en.wikipedia.org/wiki/Camel_case>`__ for project names):
 
 .. include:: ../build/autogen_tricorder_newsimproj_TriCorder.txt
   :literal:

doc/source/particlegenerators.rst

@@ -134,7 +134,7 @@ package.
 
         randomize_y=True random_min_y_meters=0.5 random_max_y_meters=1.0
     * And finally the ability to specify particle identity via `pdg code
-      <https://pdg.lbl.gov/2023/reviews/rpp2023-rev-monte-carlo-numbering.pdf>`_
+      <https://pdg.lbl.gov/2023/reviews/rpp2023-rev-monte-carlo-numbering.pdf>`__
       rather than names, and to generate more than 1 primary particle each
       event.
     * Too see all the parameters of ``FlexGen``, simply run the command::

doc/source/simplehists.rst

@@ -52,7 +52,7 @@ list of features include:
 
     * To/from raw bytes in both C++ and Python (in the form of ``std::string`` or
       ``bytes`` respectively).
-    * To work with the standard Python ``pickle`` module.
+    * They work with the standard Python ``pickle`` module.
 * Histograms can be cloned, merged, normalised, scaled, integrated, ...
 * The C++ interface is simple to use and very fast.
 * The Python interface additionally features integration with Numpy arrays and
@@ -70,7 +70,7 @@ list of features include:
       in a ``.shist`` file to `ROOT <http://root.cern.ch/>`__ histograms and store
       them in a ``.root`` file. This requires ROOT to have been installed in the
       environment, which `might not be simple
-      <https://github.com/conda-forge/root-feedstock/issues/214>`_.
+      <https://github.com/conda-forge/root-feedstock/issues/214>`__.
 
 Example: Producing histograms in C++
 -------------------------------------

doc/source/vis.rst

@@ -17,7 +17,7 @@ Custom 3D Viewer
 ----------------
 
 In dgcode, we provide a custom `OpenSceneGraph
-<https://www.openscenegraph.com/>`_-based 3D visualisation tool which can be
+<https://www.openscenegraph.com/>`__-based 3D visualisation tool which can be
 used to visualise both simulation geometries and data. Despite being a bit rough
 around the edges (for instance it could use a better name than "CoolNameHere"),
 it has already been highly useful for a lot of work so far.
@@ -216,7 +216,7 @@ the various commands that one might use in the interactive Geant4 terminal
 except to note that a few of the more useful commands are printed by dgcode in
 the terminal (see first screenshot in this section), and refer
 interested parties to the `official Geant4 documentation on visualisation
-<https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/GettingStarted/visualization.html>`_.
+<https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/GettingStarted/visualization.html>`__.
 
 Note that you exit the terminal by the command "exit" (or ``ctrl+D``, like in BASH).