From 98c4eb2a2cd7589a891cf1d19e937b0b72e6d39e Mon Sep 17 00:00:00 2001 From: Paul Romano Date: Tue, 13 Jun 2023 06:19:10 -0500 Subject: [PATCH] Several small documentation updates (#2558) --- docs/source/devguide/docbuild.rst | 17 +++++---------- docs/source/devguide/tests.rst | 18 +++++++--------- docs/source/devguide/workflow.rst | 2 +- docs/source/io_formats/particle_restart.rst | 2 ++ docs/source/io_formats/statepoint.rst | 2 +- docs/source/quickinstall.rst | 2 +- docs/source/usersguide/basics.rst | 23 ++++++--------------- docs/source/usersguide/install.rst | 20 +++++++++--------- 8 files changed, 33 insertions(+), 53 deletions(-) diff --git a/docs/source/devguide/docbuild.rst b/docs/source/devguide/docbuild.rst index 38ef628df5..389a423f3a 100644 --- a/docs/source/devguide/docbuild.rst +++ b/docs/source/devguide/docbuild.rst @@ -5,21 +5,14 @@ Building Sphinx Documentation ============================= In order to build the documentation in the ``docs`` directory, you will need to -have the `Sphinx `_ third-party Python -package. The easiest way to install Sphinx is via pip: +have the several third-party Python packages installed, including `Sphinx +`_. To install the necessary +prerequisites, provide the optional "docs" dependencies when installing OpenMC's +Python API. That is, from the root directory of the OpenMC repository: .. code-block:: sh - pip install sphinx - -Additionally, you will need several Sphinx extensions that can be installed -directly with pip: - -.. code-block:: sh - - pip install sphinx-numfig - pip install sphinxcontrib-katex - pip install sphinxcontrib-svg2pdfconverter + python -m pip install .[docs] ----------------------------------- Building Documentation as a Webpage diff --git a/docs/source/devguide/tests.rst b/docs/source/devguide/tests.rst index d076511b1d..582bb033d9 100644 --- a/docs/source/devguide/tests.rst +++ b/docs/source/devguide/tests.rst @@ -23,11 +23,7 @@ Prerequisites OpenMC in development/editable mode. With setuptools, this is accomplished by running:: - python setup.py develop - - or using pip (recommended):: - - pip install -e .[test] + python -m pip install -e .[test] - The test suite requires a specific set of cross section data in order for tests to pass. A download URL for the data that OpenMC expects can be found @@ -83,13 +79,13 @@ does not exist run:: touch test_.cpp -The file must be added to the CMake build system in -``tests/cpp_unit_tests/CMakeLists.txt``. ``test_`` should -be added to ``TEST_NAMES``. +The file must be added to the CMake build system in +``tests/cpp_unit_tests/CMakeLists.txt``. ``test_`` should +be added to ``TEST_NAMES``. -To add a test case to ``test_.cpp`` ensure -``catch2/catch_test_macros.hpp`` is included. A unit test can then be added -using the ``TEST_CASE`` macro and the ``REQUIRE`` assertion from Catch2. +To add a test case to ``test_.cpp`` ensure +``catch2/catch_test_macros.hpp`` is included. A unit test can then be added +using the ``TEST_CASE`` macro and the ``REQUIRE`` assertion from Catch2. Adding Tests to the Regression Suite ------------------------------------ diff --git a/docs/source/devguide/workflow.rst b/docs/source/devguide/workflow.rst index 6b5ec63cb5..d6a3c6ba4f 100644 --- a/docs/source/devguide/workflow.rst +++ b/docs/source/devguide/workflow.rst @@ -116,7 +116,7 @@ pip_. From the root directory of the OpenMC repository, run: .. code-block:: sh - pip install -e .[test] + python -m pip install -e .[test] This installs the OpenMC Python package in `"editable" mode `_ so that 1) diff --git a/docs/source/io_formats/particle_restart.rst b/docs/source/io_formats/particle_restart.rst index 53f86735f3..2734f0470e 100644 --- a/docs/source/io_formats/particle_restart.rst +++ b/docs/source/io_formats/particle_restart.rst @@ -26,6 +26,8 @@ The current version of the particle restart file format is 2.0. - **run_mode** (*char[]*) -- Run mode used, either 'fixed source', 'eigenvalue', or 'particle restart'. - **id** (*int8_t*) -- Unique identifier of the particle. + - **type** (*int*) -- Particle type (0=neutron, 1=photon, 2=electron, + 3=positron) - **weight** (*double*) -- Weight of the particle. - **energy** (*double*) -- Energy of the particle in eV for continuous-energy mode, or the energy group of the particle for diff --git a/docs/source/io_formats/statepoint.rst b/docs/source/io_formats/statepoint.rst index 37a379b52c..edff686b1b 100644 --- a/docs/source/io_formats/statepoint.rst +++ b/docs/source/io_formats/statepoint.rst @@ -4,7 +4,7 @@ State Point File Format ======================= -The current version of the statepoint file format is 17.0. +The current version of the statepoint file format is 18.1. **/** diff --git a/docs/source/quickinstall.rst b/docs/source/quickinstall.rst index 480db5be68..b25b02fb86 100644 --- a/docs/source/quickinstall.rst +++ b/docs/source/quickinstall.rst @@ -157,7 +157,7 @@ distribution/repository, run: .. code-block:: sh - pip install . + python -m pip install . If you want to build a parallel version of OpenMC (using OpenMP or MPI), directions can be found in the :ref:`detailed installation instructions diff --git a/docs/source/usersguide/basics.rst b/docs/source/usersguide/basics.rst index 3394c17a63..60b599588e 100644 --- a/docs/source/usersguide/basics.rst +++ b/docs/source/usersguide/basics.rst @@ -83,12 +83,12 @@ Creating Input Files .. currentmodule:: openmc The most rudimentary option for creating input files is to simply write them -from scratch using the :ref:`XML format specifications -`. This approach will feel familiar to users of other -Monte Carlo codes such as MCNP and Serpent, with the added bonus that the XML -formats feel much more "readable". Alternatively, input files can be generated -using OpenMC's :ref:`Python API `, which is introduced in the -following section. +from scratch using the :ref:`XML format specifications `. +This approach will feel familiar to users of other Monte Carlo codes such as +MCNP and Serpent, with the added bonus that the XML formats feel much more +"readable". However, it is strongly recommended to generate input files using +OpenMC's :ref:`Python API `, which is introduced in the following +section. ---------- Python API @@ -178,14 +178,3 @@ energy electronvolt eV time second s ======= ============ ====== ------------------------------------- -ERSN-OpenMC Graphical User Interface ------------------------------------- - -A third-party Java-based user-friendly graphical user interface for creating XML -input files called ERSN-OpenMC_ is developed and maintained by members of the -Radiation and Nuclear Systems Group at the Faculty of Sciences Tetouan, Morocco. -The GUI also allows one to automatically download prerequisites for installing and -running OpenMC. - -.. _ERSN-OpenMC: https://github.com/EL-Bakkali-Jaafar/ERSN-OpenMC diff --git a/docs/source/usersguide/install.rst b/docs/source/usersguide/install.rst index ed02c5d9fa..ab2cbe6454 100644 --- a/docs/source/usersguide/install.rst +++ b/docs/source/usersguide/install.rst @@ -488,13 +488,13 @@ OpenMC locally by specifying an install prefix when running cmake: The ``CMAKE_INSTALL_PREFIX`` variable can be changed to any path for which you have write-access. -Compiling on Windows 10 ------------------------ +Compiling on Windows +-------------------- -Recent versions of Windows 10 include a subsystem for Linux that allows one to -run Bash within Ubuntu running in Windows. First, follow the installation guide -`here `_ to get Bash -on Ubuntu on Windows setup. Once you are within bash, obtain the necessary +Recent versions of Windows include a subsystem for Linux that allows one to run +Bash within Ubuntu running in Windows. First, follow the installation guide +`here `_ to get Bash on +Ubuntu on Windows set up. Once you are within bash, obtain the necessary :ref:`prerequisites ` via ``apt``. Finally, follow the :ref:`instructions for compiling on linux `. @@ -522,7 +522,7 @@ distribution/repository, run: .. code-block:: sh - pip install . + python -m pip install . pip will first check that all :ref:`required third-party packages ` have been installed, and if they are not present, @@ -608,15 +608,15 @@ for OpenMC. Thus, the install process would proceed as follows: make install cd .. - MPICC= pip install mpi4py - HDF5_DIR= pip install --no-binary=h5py h5py + MPICC= python -m pip install mpi4py + HDF5_DIR= python -m pip install --no-binary=h5py h5py If you are using parallel HDF5, you'll also need to make sure the right MPI wrapper is used when installing h5py: .. code-block:: sh - CC= HDF5_MPI=ON HDF5_DIR= pip install --no-binary=h5py h5py + CC= HDF5_MPI=ON HDF5_DIR= python -m pip install --no-binary=h5py h5py .. _Conda: https://conda.io/en/latest/ .. _pip: https://pip.pypa.io/en/stable/