Merge pull request #1371 from paulromano/doc-updates

Documentation fixes and updates

Author: drewejohnson

docs/source/conf.py

@@ -27,7 +27,7 @@
     'scipy.interpolate', 'scipy.integrate', 'scipy.optimize', 'scipy.special',
     'scipy.stats', 'scipy.spatial', 'h5py', 'pandas', 'uncertainties',
     'matplotlib', 'matplotlib.pyplot', 'openmoc',
-    'openmc.data.reconstruct'
+    'openmc.data.reconstruct', 'openmc.checkvalue'
 ]
 sys.modules.update((mod_name, MagicMock()) for mod_name in MOCK_MODULES)
 

docs/source/devguide/docbuild.rst

@@ -5,27 +5,28 @@ Building Sphinx Documentation
 =============================
 
 In order to build the documentation in the ``docs`` directory, you will need to
-have the `Sphinx <http://openmc.readthedocs.io/en/latest/>`_ third-party Python
+have the `Sphinx <https://www.sphinx-doc.org/en/master/>`_ third-party Python
 package. The easiest way to install Sphinx is via pip:
 
 .. code-block:: sh
 
-    sudo pip install sphinx
+    pip install sphinx
 
-Additionally, you will also need a Sphinx extension for numbering figures. The
-`Numfig <http://openmc.readthedocs.io/en/latest/>`_ package can be installed
+Additionally, you will need several Sphinx extensions that can be installed
 directly with pip:
 
 .. code-block:: sh
 
-   sudo pip install sphinx-numfig
+    pip install sphinx-numfig
+    pip install sphinxcontrib-katex
+    pip install sphinxcontrib-svg2pdfconverter
 
 -----------------------------------
 Building Documentation as a Webpage
 -----------------------------------
 
 To build the documentation as a webpage (what appears at
-http://openmc.readthedocs.io), simply go to the ``docs`` directory and run:
+https://docs.openmc.org), simply go to the ``docs`` directory and run:
 
 .. code-block:: sh
 

docs/source/devguide/docker.rst

@@ -19,7 +19,7 @@ build a Docker image with OpenMC installed. The image includes OpenMC with
 MPICH and parallel HDF5 in the ``/opt/openmc`` directory, and
 `Miniconda3 <https://conda.io/miniconda.html>`_ with all of the Python
 pre-requisites (NumPy, SciPy, Pandas, etc.) installed. The
-`NJOY2016 <http://www.njoy21.io/NJOY2016/>`_ codebase is installed in
+`NJOY2016 <https://www.njoy21.io/NJOY2016/>`_ codebase is installed in
 ``/opt/NJOY2016`` to support full functionality and testing of the
 ``openmc.data`` Python module. The publicly available nuclear data libraries
 necessary to run OpenMC's test suite -- including NNDC and WMP cross sections
@@ -54,4 +54,3 @@ Docker container where you have access to use OpenMC.
 .. _Docker container: https://www.docker.com/resources/what-container
 .. _options: https://docs.docker.com/engine/reference/commandline/run/
 .. _mounting volumes: https://docs.docker.com/storage/volumes/
-

docs/source/devguide/styleguide.rst

@@ -207,8 +207,8 @@ Documentation
 -------------
 
 Classes, structs, and functions are to be annotated for the `Doxygen
-<http://www.stack.nl/~dimitri/doxygen/>`_ documentation generation tool. Use the
-``\`` form of Doxygen commands, e.g., ``\brief`` instead of ``@brief``.
+<http://www.doxygen.nl/>`_ documentation generation tool. Use the ``\`` form of
+Doxygen commands, e.g., ``\brief`` instead of ``@brief``.
 
 ------
 Python
@@ -231,7 +231,7 @@ represent a filesystem path should work with both strings and Path_ objects.
 .. _C++ Core Guidelines: http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines
 .. _PEP8: https://www.python.org/dev/peps/pep-0008/
 .. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
-.. _numpy: http://www.numpy.org/
+.. _numpy: https://numpy.org/
 .. _scipy: https://www.scipy.org/
 .. _matplotlib: https://matplotlib.org/
 .. _pandas: https://pandas.pydata.org/

docs/source/devguide/workflow.rst

@@ -124,7 +124,7 @@ can interfere with virtual environments.
 .. _GitHub: https://github.com/
 .. _git flow: http://nvie.com/git-model
 .. _valgrind: http://valgrind.org/
-.. _style guide: http://openmc.readthedocs.io/en/latest/devguide/styleguide.html
+.. _style guide: https://docs.openmc.org/en/latest/devguide/styleguide.html
 .. _pull request: https://help.github.com/articles/using-pull-requests
 .. _openmc-dev/openmc: https://github.com/openmc-dev/openmc
 .. _paid plan: https://github.com/plans

docs/source/index.rst

@@ -2,12 +2,14 @@
 The OpenMC Monte Carlo Code
 ===========================
 
-OpenMC is a Monte Carlo particle transport simulation code focused on neutron
-criticality calculations. It is capable of simulating 3D models based on
-constructive solid geometry with second-order surfaces. OpenMC supports either
-continuous-energy or multi-group transport.  The continuous-energy particle
+OpenMC is a community-developed Monte Carlo neutron and photon transport
+simulation code. It is capable of performing fixed source, k-eigenvalue, and
+subcritical multiplication calculations on models built using either a
+constructive solid geometry or CAD representation. OpenMC supports both
+continuous-energy and multigroup transport. The continuous-energy particle
 interaction data is based on a native HDF5 format that can be generated from ACE
-files used by the MCNP and Serpent Monte Carlo codes.
+files produced by NJOY. Parallelism is enabled via a hybrid MPI and OpenMP
+programming model.
 
 OpenMC was originally developed by members of the `Computational Reactor Physics
 Group <http://crpg.mit.edu>`_ at the `Massachusetts Institute of Technology

docs/source/io_formats/settings.rst

@@ -333,7 +333,7 @@ or sub-elements:
     velocity sampling) or "dbrc" (Doppler broadening rejection correction).
     Descriptions of each of these methods are documented here_.
 
-    .. _here: http://dx.doi.org/10.1016/j.anucene.2017.12.044
+    .. _here: https://doi.org/10.1016/j.anucene.2017.12.044
 
     *Default*: "rvs"
 

docs/source/io_formats/statepoint.rst

@@ -109,7 +109,8 @@ The current version of the statepoint file format is 17.0.
 
 **/tallies/tally <uid>/**
 
-:Attributes: - **internal** (*int*) -- Flag indicating the presence of tally
+:Attributes:
+             - **internal** (*int*) -- Flag indicating the presence of tally
                data (0) or absence of tally data (1). All user defined
                tallies will have a value of 0 unless otherwise instructed.
 

docs/source/methods/cmfd.rst

@@ -538,7 +538,7 @@ Examples of CMFD simulations using OpenMC can be found in [HermanThesis]_.
    .. rubric:: References
 
 .. [BEAVRS] Nick Horelik, Bryan Herman. *Benchmark for Evaluation And Verification of Reactor
-            Simulations*. Massachusetts Institute of Technology, http://crpg.mit.edu/pub/beavrs
+            Simulations*. Massachusetts Institute of Technology, https://crpg.mit.edu/research/beavrs
             , 2013.
 
 .. [Gill] Daniel F. Gill. *Newton-Krylov methods for the solution of the k-eigenvalue problem in

docs/source/methods/cross_sections.rst

@@ -8,13 +8,14 @@ Cross Section Representations
 Continuous-Energy Data
 ----------------------
 
-The data governing the interaction of neutrons with
-various nuclei for continous-energy problems are represented using the ACE
-format which is used by MCNP_ and Serpent_. ACE-format data can be generated
-with the NJOY_ nuclear data processing system which converts raw
-`ENDF/B data`_ into linearly-interpolable data as required by most Monte Carlo
-codes. The use of a standard cross section format allows for a direct comparison
-of OpenMC with other codes since the same cross section libraries can be used.
+In OpenMC, the data governing the interaction of neutrons with various nuclei
+for continous-energy problems are represented using an HDF5 format that can be
+produced by converting files in the ACE format, which is used by MCNP_ and
+Serpent_. ACE-format data can be generated with the NJOY_ nuclear data
+processing system, which converts raw `ENDF/B data`_ into linearly-interpolable
+data as required by most Monte Carlo codes. Since ACE-format data can be
+converted into OpenMC's HDF5 format, it is possible to perform direct comparison
+of OpenMC with other codes using the same underlying nuclear data library.
 
 The ACE format contains continuous-energy cross sections for the following types
 of reactions: elastic scattering, fission (or first-chance fission,
@@ -31,7 +32,7 @@ data can be used.
 Energy Grid Methods
 -------------------
 
-The method by which continuous energy cross sections for each nuclide in a
+The method by which continuous-energy cross sections for each nuclide in a
 problem are stored as a function of energy can have a substantial effect on the
 performance of a Monte Carlo simulation. Since the ACE format is based on
 linearly-interpolable cross sections, each nuclide has cross sections tabulated
@@ -72,9 +73,9 @@ Windowed Multipole Representation
 ---------------------------------
 
 In addition to the usual pointwise representation of cross sections, OpenMC
-offers support for an experimental data format called windowed multipole (WMP).
-This data format requires less memory than pointwise cross sections, and it
-allows on-the-fly Doppler broadening to arbitrary temperature.
+offers support for a data format called windowed multipole (WMP). This data
+format requires less memory than pointwise cross sections, and it allows
+on-the-fly Doppler broadening to arbitrary temperature.
 
 The multipole method was introduced by Hwang_ and the faster windowed multipole
 method by Josey_. In the multipole format, cross section resonances are
@@ -258,7 +259,7 @@ where a material has a very large cross sections relative to the other material
 used to minimize this error.
 
 Finally, the above options for representing the physics do not have to be
-consistent across the problem.  The number of groups and the structure, however,
+consistent across the problem. The number of groups and the structure, however,
 does have to be consistent across the data sets. That is to say that each
 microscopic or macroscopic data set does not have to apply the same scattering
 expansion, treatment of multiplicity or angular representation of the cross
@@ -269,11 +270,11 @@ or even isotropic scattering.
 .. _logarithmic mapping technique:
    https://laws.lanl.gov/vhosts/mcnp.lanl.gov/pdf_files/la-ur-14-24530.pdf
 .. _Hwang: http://www.ans.org/pubs/journals/nse/a_16381
-.. _Josey: http://dx.doi.org/10.1016/j.jcp.2015.08.013
+.. _Josey: https://doi.org/10.1016/j.jcp.2015.08.013
 .. _WMP Library: https://github.com/mit-crpg/WMP_Library
 .. _MCNP: http://mcnp.lanl.gov
 .. _Serpent: http://montecarlo.vtt.fi
 .. _NJOY: http://t2.lanl.gov/codes.shtml
 .. _ENDF/B data: http://www.nndc.bnl.gov/endf
-.. _Leppanen: http://dx.doi.org/10.1016/j.anucene.2009.03.019
+.. _Leppanen: https://doi.org/10.1016/j.anucene.2009.03.019
 .. _algorithms: http://ab-initio.mit.edu/wiki/index.php/Faddeeva_Package