Several suggested changes to the documentation (#23)

* fix typos and proper noun capitalisations in docs

* Minor fixes in the documentation

* fix external links and other minor issues with the documentation

* added possibly needed space before < in :ref:

* remaining ':ref:'s fixed in doc

* removed leftover half sentence from the documentation

doc/source/about.rst

@@ -4,8 +4,8 @@ About
 
 .. include:: cite.rst
 
-Please report any bugs, problems or feature requests related to simplebuild 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/extractg4xs.rst

@@ -3,7 +3,7 @@
 Investigate cross sections
 ==========================
 
-It is is not in general straight-forward to extract information about applied
+It is not in general straight-forward to extract information about applied
 interaction cross sections and associated mean free path lengths from
 Geant4. Therefore, a custom mechanism was created in dgcode in the
 :sbpkg:`G4XSectDump` package, to address this issue. Rather than attempting to
@@ -23,7 +23,7 @@ it in principle also works with any material and physics list.
 
    However, non-neutron, non-scattering, or non-thermal cross sections of the
    material in the Geant4 simulations are not provided by ``nctool``, and must
-   be investigated by using the tools discussed on the present page. Dilligent
+   be investigated by using the tools discussed on the present page. Diligent
    users might wish to investigate a given material using both approaches.
 
 How to extract cross sections
@@ -77,7 +77,7 @@ with ``'`` characters. This is in general a good idea, since such strings might
 contain special characters which could be otherwise be interpreted by your shell
 rather than being passed to ``sb_g4xsectdump_query``.
 
-In addition to launching interactive matplotlib-based cross section plots,
+In addition to launching interactive Matplotlib-based cross section plots,
 either of the above commands produce a list of data files with cross section
 information, a file with a dump of the G4Material, and files with plots like the
 following:

doc/source/geo.rst

@@ -28,7 +28,7 @@ possibilities for how one can construct a geometry in Geant4, and it is
 recommended to also spend some time reading about `geometry defintions in the
 Geant4 documentation
 <https://geant4-userdoc.web.cern.ch/UsersGuides/AllGuides/html/ForApplicationDevelopers/Detector/Geometry/geometry.html>`__
-(note that for historical reasons geometry definition is often refered to as
+(note that for historical reasons geometry definition is often referred to as
 "Detector definition" in Geant4). At the very least, it is important to have a
 clear understanding of the difference between the Geant4 concepts of a *solid*
 (a geometrical shape like a box or cylinder), a *logical volume* (a solid which
@@ -86,10 +86,10 @@ One final thing to note in the above, is that in dgcode we have a convenience
 method called ``place(..)``, which is used to directly combine a shape with a
 material and a position. As can be seen in the implementation
 :sbpkg:`here<G4Interfaces/libsrc/GeoBase.cc>`, this is really just wrapping
-completely standard Geant4 code. Feel free to use this function or not as you
+completely standard Geant4 code. Feel free to use this function or not, as you
 wish.
 
-For completeness we show how some or all of the parameters might be modified in
+For completeness, we show how some or all of the parameters might be modified in
 a Python :ref:`sim-script <sbsimscript>`:
 
 .. literalinclude:: ../build/autogen_tricorder_simscript_wocomments.py

doc/source/gravity.rst

@@ -2,7 +2,7 @@ Gravity
 ================
 
 A global gravity field for neutrons can be enabled using the G4GravityHelper
-module in the framework by adding two lines in your main python script (the
+module in dgcode by adding two lines in your main Python script (the
 "sim-script"):
 
 .. code-block:: python

doc/source/griff.rst

@@ -6,15 +6,15 @@ Griff
 
 A general purpose object oriented output file format, Griff (**G**\ eant4 **R**\
 esults **I**\ n **F**\ riendly **F**\ ormat), with meta-data has been
-implemented in our CodingFramework, in order to facilitate a faster turn-around
+implemented in dgcode, in order to facilitate a faster turn-around
 time when setting up and analysing simulations, as well as allowing more complex
 and detailed whole-event analyses. Based on custom serialisation code, it is
 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
 -------------
@@ -62,8 +62,8 @@ filtering performed during analysis of Griff files, described in a section
 further down this page):
 
 * **Reduce step data globally:** Due to the contained coordinates, step data
-  requires the most disk space, and the primary global filtering method is
-  therefore to reduce the amount of steps written out. Either by completely
+  requires the most disk space; therefore, the primary global filtering method
+  is to reduce the amount of steps written out. Either by completely
   omitting step data, or by combining all steps on a segment into one
   meta-step. Conveniently controlled by a global flag, there are thus three
   available modes:
@@ -79,13 +79,13 @@ further down this page):
 
 * **Custom output filters:** Alternatively, users can register custom
   step-filters, thereby gaining complete control of the stored output. Step
-  filters implements
+  filters implement
   :sbpkg:`StepFilterBase<G4Interfaces/libinc/StepFilterBase.hh>` and essentially
   filters each G4Step instance during Geant4 simulation. The potential gain in
   file-size from this are huge, but the downside is obviously that the whole
-  event is no longer available (i.e. when analysing one can't be certain that a
+  event is no longer available (i.e. when analysing, one can't be certain that a
   track has all of its segments, steps or daughter tracks available). They can
-  be activated from either python or C++. A few premade examples of such filters
+  be activated from either Python or C++. A few premade examples of such filters
   reside in the :sbpkg:`G4CollectFilters` package, but users are free to
   implement their own:
 
@@ -138,7 +138,7 @@ If for some reason you are *not* using the standard :sbpkg:`G4Launcher`-based
 sim scrips, you can enable Griff output with the following command (after
 including the
 :sbpkg:`G4DataCollect/G4DataCollect.hh<G4DataCollect/libinc/G4DataCollect.hh>`
-header file.  from the :sbpkg:`G4DataCollect` package):
+header file from the :sbpkg:`G4DataCollect` package):
 
 .. code-block:: python
 
@@ -182,9 +182,9 @@ efficient analysis code. The basic idea is that before the loop over events
 begins, one declares one or more iterators for
 :sbpkg:`tracks<GriffAnaUtils/libinc/TrackIterator.hh>`,
 :sbpkg:`segments<GriffAnaUtils/libinc/SegmentIterator.hh>` or
-:sbpkg:`steps<GriffAnaUtils/libinc/StepIterator.hh>` and assigns filters to them
-so that during the event loop they can be used to iterate over just the parts of
-each event which is of interest.
+:sbpkg:`steps<GriffAnaUtils/libinc/StepIterator.hh>`, and assigns filters to
+them so that during the event loop they can be used to iterate over just the
+parts of each event which is of interest.
 
 The :sbpkg:`basic analysis example<GriffAnaEx/app_testcppana_basic/main.cc>`
 from the previous section rewritten to use iterators and selection filters is
@@ -199,8 +199,8 @@ obviously):
 
 * Iterators:
 
-  * :sbpkg:`TrackIterator<GriffAnaUtils/libinc/TrackIterator.hh>`,
-  * :sbpkg:`SegmentIterator<GriffAnaUtils/libinc/SegmentIterator.hh>`,
+  * :sbpkg:`TrackIterator<GriffAnaUtils/libinc/TrackIterator.hh>`
+  * :sbpkg:`SegmentIterator<GriffAnaUtils/libinc/SegmentIterator.hh>`
   * :sbpkg:`StepIterator<GriffAnaUtils/libinc/StepIterator.hh>`
 
 * Track filters:
@@ -230,7 +230,7 @@ Python API
 ^^^^^^^^^^
 
 For convenience, all the Griff analysis classes are available in Python as well
-as C++. This allows one to write analyses in python just as (or rather, more)
+as in C++. This allows one to write analyses in Python just as (or rather, more)
 easily than in C++, as well as doing away with the need of a compilation in the
 *edit* → *compile* → *run* analysis cycle typically carried out.
 
@@ -244,8 +244,8 @@ There is also another advanced example in
 :sbpkg:`GriffAnaTests/scripts/testiter_py`.
 
 There is unfortunately one major downside of performing the analysis in Python
-rather than C++, and that is that it can be a lot slower. Mostly, this does not
-matter, but when one have loops with a high number of events, then any
+rather than in C++, and that is that it can be a lot slower. Mostly, this does
+not matter, but when one have loops with a high number of events, then any
 difference in speed per event will obviously be noticeable. If using the
 "advanced" analysis approach with iterators and selection filters, the act of
 accessing the Griff data itself will be almost as fast in Python as in
@@ -259,12 +259,12 @@ speed is a concern, but for smaller statistics (say, millions of particles
 simulated), Python remains a great option for quickly putting some plots
 together. A typical analysis approach in case of very large statistics would be
 to carry out the initial analysis in C++, writing out histograms
-(cf. :ref:`SimpleHists<sbsimplehists>`), and then performing further analysis
+(cf. :ref:`SimpleHists <sbsimplehists>`), and then performing further analysis
 and plot production in Python, using those histograms (and perhaps also the
 job-level metadata from Griff).
 
 Command-line utilities
-======================
+----------------------
 
 A few command-line utilities are provided:
 
@@ -276,23 +276,23 @@ A few command-line utilities are provided:
   that it can be used to verify the integrity of the data, in case one is
   suspicious that a file might have become corrupted.
 * ``sb_g4osg_viewgriff``: Can be used to visualise the data inside a file with
-  our :ref:`custom viewer<sb3dvis>`.
+  our :ref:`custom viewer <sb3dvis>`.
 * ``sb_griffanautils_extractevts``: Can be used to select and extract a few
   events from a large griff file into a smaller one. Run with ``--help`` for
   instructions.
 
 Implementation
-==============
+--------------
 
 .. image:: images/griff_userview.png
 
 Hidden from the user, the actual on-disk layout of Griff files is illustrated in
-the figure on the right: after a short file header, one event block is appended
+the figure above: after a short file header, one event block is appended
 for each event. Data inside the block is kept in three sections containing
 shared, brief and full data respectively. Data unique to individual tracks,
 segments and steps is kept in the two latter, while as the name implies, common
 data relevant across events is kept in the shared data section. This includes
-any strings and metadata relating to volumes, particles and job configuration,
+any strings and metadata relating to volumes, particles, and job configuration,
 which can then be referenced economically through simple indices in the other
 sections (in current and following events). This means that in order to load the
 ``N``'th event, the shared data sections of events 1 through ``N`` must have
@@ -315,14 +315,13 @@ for a particular segment if needed.
 The actual code implementing Griff is spread over several packages:
 
 :sbpkg:`EvtFile` :
-  Package implementing the container format with file and
-  event header and section blocks as illustrated in the image above/to the
-  right), even skipping, and associated disk I/O and compression.
-
+  Package implementing the container format with file and event header, section
+  blocks (as illustrated in the image above), event skipping, and
+  associated disk I/O and compression.
 
 :sbpkg:`GriffFormat` :
   Package with common definitions used by both reader and
-  writer modules. Also contains command-line scripts for inspecting griff files
+  writer modules. Also contains command-line scripts for inspecting Griff files
   (``sb_griffformat_info`` and ``sb_griffformat_dumpfile``).
 
 :sbpkg:`GriffDataRead` :

doc/source/heatmap.rst

@@ -23,7 +23,7 @@ available parameters in the ``QUANTITY`` and ``CONDITION`` expressions.
 
 Resulting heatmap files have the extension ``.mesh3d`` and can be inspected
 interactively via the ``sb_mesh3d_browse command``, leading to an interactive
-display where one can view the 3D data projected onto any cartesian plane and
+display where one can view the 3D data projected onto any cartesian plane, and
 optionally only using data from selected slices of the third dimension. See the
 image above for an example.
 

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

@@ -16,10 +16,10 @@ Install via conda
 ..
   Fixme: add conda badges
 
-The recommended and easiest way to install dgcode, is by creating an
+The recommended and easiest way to install dgcode is by creating an
 appropriate conda environment based on the `conda-forge
 <https://conda-forge.org/>`__ channel, in which all the dependencies are
-included. The package for dgcode itself, must still be installed via the PyPI
+included. The package for dgcode itself must still be installed via the PyPI
 (pip) package for the time being, although that will change at some point in the
 future (cf. `#9
 <https://github.com/mctools/simplebuild-dgcode/issues/9>`__). The recommended
@@ -56,8 +56,9 @@ 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
-all the necessary build tools. For special advanced use-cases, experts might
+`simplebuild
+<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
 case, one can simply install dgcode via ``pip``, either via a PyPI package
@@ -111,9 +112,9 @@ is because the scattering physics in the aluminium in this example is provided
 by NCrystal as ``stdlib::Al_sg225.ncmat;comp=bragg`` (i.e. only Bragg
 diffraction is enabled), so all (singly) scattered neutrons (green) should end
 up in a single Debye-Scherrer cone. Other particles like gammas (yellow) are
-generated in absorption events, based on Geant4's own builtin physics.
+generated in absorption events, based on Geant4's own built-in physics.
 
-It might also be a good idea to verify that the matplotlib-based
+It might also be a good idea to verify that the Matplotlib-based
 :ref:`SimpleHists <sbsimplehists>` plotting works, which can be done with the
 command::
 
@@ -136,7 +137,7 @@ Which should launch an interactive browser looking like:
 
 There is only 1 histogram inside this particular file, so the browser is not
 particular useful in this case. But you can still test that it works by
-confirming that clicking on the histogram resuls in that histogram being shown.
+confirming that clicking on the histogram results in that histogram being shown.
 
 .. |image_example_dataviewer| image:: images/dgcode_launcher_example_dataviewer.png
 .. |image_shist_example| image:: images/shist_example.png

doc/source/intro.rst

@@ -8,7 +8,7 @@ of `simplebuild <https://mctools.github.io/simplebuild>`__ packages
 <sbhistory>` goes back to 2012, but in 2023/2024 it was cleaned up and
 resurrected in its present form.
 
-Most importantly, dgcode includes functionality for easy seting up and launching
+Most importantly, dgcode includes functionality for easy setting up and launching
 of Geant4 simulation jobs based on configurable :ref:`geometry <sbgeo>` and
 :ref:`generator <sbparticlegen>` modules, and contains various functionality for
 :ref:`material definitions <sbmatdef>`, :ref:`physics lists <sbphyslist>`
@@ -23,7 +23,7 @@ eventually also be a good idea to dive into parts of the `Geant4 documentation
 <https://geant4-userdoc.web.cern.ch/UsersGuides/AllGuides/html/>`__, in
 particular the parts about `geometry definitions
 <https://geant4-userdoc.web.cern.ch/UsersGuides/AllGuides/html/ForApplicationDevelopers/Detector/Geometry/geometry.html>`__
-(note that for historical reasons geometry definition is often refered to as
+(note that for historical reasons geometry definition is often referred to as
 "Detector definition" in Geant4).
 
 Features
@@ -68,10 +68,10 @@ 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
-  SimpleHists 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 `SciPy <https://scipy.org/>`__) are
-  available.
+  :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
+  `SciPy <https://scipy.org/>`__) are available.
 
 * Due in particular to being based on `simplebuild
   <https://mctools.github.io/simplebuild>`__, dgcode readily facilitates
@@ -86,11 +86,11 @@ instructions <sbinstall>`, to ensure that dgcode and simplebuild are available
 on the system. It is probably best to then spend a bit of time on the
 `simplebuild documentation <https://mctools.github.io/simplebuild/>`__, focusing
 at least on the introduction and usage examples. Then, it is probably time to
-try to followed the instructions for :ref:`how to easily start a dgcode-based
+try to follow the instructions for :ref:`how to easily start a dgcode-based
 simulation project <sbnewsimproject>`.
 
 After these initial steps, it will be time to start diving into the more
 detailed parts of the documentation, which you can find either from the sidebar
 menu or via the :ref:`subjects overview page <sbsubjects>`. You can of course
-also use the documentations search functionality in case you can not easily find
-something.
+also use the documentation's search functionality in case you can not easily
+find something.

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: