Improving Documentation (#1564)

terrapower · Dec 21, 2023 · 1d6c7ad · 1d6c7ad
1 parent 09a5e0a
commit 1d6c7ad
Show file tree

Hide file tree

Showing 17 changed files with 64 additions and 27 deletions.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -29,5 +29,5 @@
 
 - [ ] The [release notes](https://terrapower.github.io/armi/release/index.html) (location `doc/release/0.X.rst`) are up-to-date with any important changes.
 - [ ] The [documentation](https://terrapower.github.io/armi/developer/tooling.html#document-it) is still up-to-date in the `doc` folder.
-- [ ] No [requirements](https://terrapower.github.io/armi/developer/tooling.html#watch-for-requirements) were altered.
+- [ ] If any [requirements](https://terrapower.github.io/armi/developer/tooling.html#watch-for-requirements) were affected, mention it in the [release notes](https://terrapower.github.io/armi/release/index.html).
 - [ ] The dependencies are still up-to-date in `pyproject.toml`.
diff --git a/doc/developer/documenting.rst b/doc/developer/documenting.rst
@@ -1,5 +1,7 @@
+****************
 Documenting ARMI
-================
+****************
+
 ARMI uses the `Sphinx <https://www.sphinx-doc.org/en/master/>`_ documentation system to compile the 
 web-based documentation from in-code docstrings and hand-created 
 `ReStructedText files <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.

diff --git a/doc/developer/entrypoints.rst b/doc/developer/entrypoints.rst
@@ -1,5 +1,6 @@
+************
 Entry Points
-============
+************
 
 **Entry Points** are like the verbs that your App can *do*.
 The :py:mod:`built-in entry points <armi.cli>`

diff --git a/doc/developer/first_time_contributors.rst b/doc/developer/first_time_contributors.rst
@@ -9,7 +9,7 @@ Although fewer laws apply to open source materials because they are publicly-ava
 must comply with all applicable laws and regulations.
 
 Help Wanted
-===========
+-----------
 
 There are a lot of places you can get started to help the ARMI project and team:
 
@@ -22,7 +22,7 @@ There are a lot of places you can get started to help the ARMI project and team:
 Naturally, you can also look at the open `ARMI issues <https://github.com/terrapower/armi/issues>`_ to see what work needs to be done. In particular, check out the `help wanted tickets <https://github.com/terrapower/armi/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22>`_ and `good first issue tickets <https://github.com/terrapower/armi/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22>`_.
 
 Testing
-=======
+-------
 
 Any contribution must pass all included unit tests. You will frequently have to fix
 tests your code changes break. And you should definitely add tests to cover anything
@@ -42,7 +42,7 @@ Or the tests can also be run using ``pytest`` directly::
     $ pytest -n 4 armi
 
 Submitting Changes
-==================
+------------------
 
 To submit a change to ARMI, you will have to open a Pull Request (PR) on GitHub.com.
 
@@ -64,7 +64,7 @@ See our published documentation for a complete guide to our :doc:`coding standar
 Also, please check out our (quick) synopsis on :doc:`good commit messages </developer/tooling>`.
 
 Licensing of Tools
-==================
+------------------
 
 Be careful when including any dependency in ARMI (say in the ``pyproject.toml`` file) not
 to include anything with a license that superceeds our Apache license. For instance,

diff --git a/doc/developer/parallel_coding.rst b/doc/developer/parallel_coding.rst
@@ -1,6 +1,6 @@
-#####################
+*********************
 Parallel Code in ARMI
-#####################
+*********************
 
 ARMI simulations can be parallelized using the `mpi4py <https://mpi4py.readthedocs.io/en/stable/mpi4py.html>`_
 module. You should go there and read about collective and point-to-point communication if you want to

diff --git a/doc/developer/profiling.rst b/doc/developer/profiling.rst
@@ -1,6 +1,7 @@
 **************
 Profiling ARMI
 **************
+
 Python in slow, so it's important to profile code to keep it running reasonbly quickly. Using the 
 basic `Python profiler <https://docs.python.org/3/library/profile.html>`_ is the best way to get started. 
 Once you have a ``.stats`` file, however, we highly recommend using a visualizer.  

diff --git a/doc/developer/reports.rst b/doc/developer/reports.rst
@@ -1,5 +1,7 @@
+***************
 Reports in ARMI
-================
+***************
+
 .. note::  The resulting report itself is an HTML page with table of contents on the left.
 
 ARMI provides the ability to make a variety of plots and tables describing the state of the reactor.

diff --git a/doc/developer/tooling.rst b/doc/developer/tooling.rst
@@ -1,5 +1,6 @@
+**************************
 Tooling and Infrastructure
-==========================
+**************************
 
 Good Commit Messages
 --------------------
@@ -87,18 +88,19 @@ Such breadcrumbs will look like:
 .. code-block::
 
     """
-    .. req: This is a requirement breadcrumb.
+    .. test: This is a requirement test breadcrumb.
 
-    .. test: This is a test breadcrumb.
-
-    .. impl: This is an implementation breadcrumb.
+    .. impl: This is an requirement implementation breadcrumb.
 
     """
 
-If you touch any code that has such a docstring, even in a file, you are going to be
+If you touch any code that has such a docstring, even at the top of the file, you are going to be
 responsible for not breaking that code/functionality. And you will be required to explicitly
 call out that you touch such a code in your PR.
 
+Your PR reviewer will take an extra look at any PR that touches a requirement test or implementation.
+And you will need to add a special release note under the "Changes that Affect Requirements" section header.
+
 Packaging and dependency management
 -----------------------------------
 The process of packaging Python projects and managing their dependencies is somewhat

diff --git a/doc/release/0.3.rst b/doc/release/0.3.rst
@@ -2,12 +2,30 @@
 ARMI v0.3 Release Notes
 =======================
 
+ARMI v0.3.1
+============
+Release Date: TBD
+
+What's new in ARMI?
+-------------------
+#. TBD
+
+Bug Fixes
+---------
+#. TBD
+
+Changes that Affect Requirements
+--------------------------------
+
+#. TBD
+
+
 ARMI v0.3.0
 ============
 Release Date: 2023-12-21
 
-What's new in ARMI
-------------------
+What's new in ARMI?
+-------------------
 #. The ``_copyInputsHelper()`` gives relative path and not absolute after copy. (`PR#1416 <https://github.com/terrapower/armi/pull/1416>`_)
 #. Attempt to set representative block number densities by component if possible. (`PR#1412 <https://github.com/terrapower/armi/pull/1412>`_)
 #. Use ``functools`` to preserve function attributes when wrapping with ``codeTiming.timed`` (`PR#1466 <https://github.com/terrapower/armi/pull/1466>`_)

diff --git a/doc/user/accessingEntryPoints.rst b/doc/user/accessingEntryPoints.rst
@@ -1,6 +1,6 @@
+**********************
 Accessing Entry Points 
-======================
-
+**********************
 
 Reports Entry Point
 -------------------

diff --git a/doc/user/assembly_parameters_report.rst b/doc/user/assembly_parameters_report.rst
@@ -1,5 +1,7 @@
+*******************
 Assembly Parameters
-===================
+*******************
+
 This document lists all of the Assembly Parameters that are provided by the ARMI Framework.
 
 .. exec::

diff --git a/doc/user/block_parameters_report.rst b/doc/user/block_parameters_report.rst
@@ -1,5 +1,7 @@
+****************
 Block Parameters
-================
+****************
+
 This document lists all of the Block Parameters that are provided by the ARMI Framework.
 
 .. exec::

diff --git a/doc/user/component_parameters_report.rst b/doc/user/component_parameters_report.rst
@@ -1,5 +1,7 @@
+********************
 Component Parameters
-====================
+********************
+
 This document lists all of the Component Parameters that are provided by the ARMI Framework.
 
 .. exec::

diff --git a/doc/user/core_parameters_report.rst b/doc/user/core_parameters_report.rst
@@ -1,5 +1,7 @@
+***************
 Core Parameters
-===============
+***************
+
 This document lists all of the Core Parameters that are provided by the ARMI Framework.
 
 .. exec::

diff --git a/doc/user/radial_and_axial_expansion.rst b/doc/user/radial_and_axial_expansion.rst
@@ -1,6 +1,6 @@
-*******************************************
+******************************************
 Radial and Axial Expansion and Contraction
-*******************************************
+******************************************
 
 ARMI natively supports linear expansion in both the radial and axial dimensions. These expansion types function independently of one another and each have their own set of underlying assumptions and use-cases. The remainder of this section is described as follows: in Section :ref:`thermalExpansion` the methodology used for thermal expansion within ARMI is described; in Sections :ref:`radialExpansion` and :ref:`axialExpansion`, we describe the design, limitations, and intended functionality of radial and axial expansion, respectively.
 

diff --git a/doc/user/reactor_parameters_report.rst b/doc/user/reactor_parameters_report.rst
@@ -1,5 +1,7 @@
+******************
 Reactor Parameters
-==================
+******************
+
 This document lists all of the Reactor Parameters that are provided by the ARMI Framework.
 
 .. exec::

diff --git a/doc/user/user_install.rst b/doc/user/user_install.rst
@@ -1,6 +1,7 @@
 ************
 Installation
 ************
+
 This section will guide you through installing the ARMI Framework on your machine.
 
 Prerequisites