Merge pull request #147 from jpmorgan98/main

Documentation and Testing

.github/workflows/mpi_numba_reg.yml

@@ -8,7 +8,7 @@ jobs:
     strategy:
         fail-fast: false
         matrix:
-            os: ["ubuntu-latest", "macos-latest"]
+            os: ["ubuntu-latest"] #, "macos-latest"
     steps:
     - uses: actions/checkout@v3
     - name: Set up python 3.11

.github/workflows/mpi_reg.yml

@@ -8,7 +8,7 @@ jobs:
     strategy:
         fail-fast: false
         matrix:
-            os: ["ubuntu-latest", "macos-latest"]
+            os: ["ubuntu-latest"] #, "macos-latest"
     steps:
     - uses: actions/checkout@v3
     - name: Set up python 3.11

.gitignore

@@ -16,6 +16,7 @@ __pycache__
 # Editor
 .spyproject
 *.swp
+.vscode/
 
 # Output
 *output.h5

docs/source/contribution.rst

@@ -11,20 +11,23 @@ We have regular developers meetings for any and all who are interested to discus
 
 This describes the processes of contributing to MC/DC for both internal (CEMeNT) and external developers.
 
-Please note our `code of conduct <>` which we take seriously
+Please note our `code of conduct <https://github.com/CEMeNT-PSAAP/MCDC/blob/main/CODE_OF_CONDUCT.md>`_ which we take seriously
 
 ------------
 Code Styling
 ------------
 
-Our code is autolinted for the `Black code style <https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html>`.
+Our code is auto-linted for the `Black code style <https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html>`_.
 Your contributions will not be merged unless you follow this code style.
 It's pretty easy to do this locally, just run,
 
 .. code-block:: sh
+
+
     pip install black
     black .
 
+
 in the top level MC/DC directory and all necessary changes will be automatically made for you.
 
 -------
@@ -38,20 +41,25 @@ A regression test suite (including models with analytical and experimental solut
 
 Our test suite runs on every PR, and Push.
 Our github based CI runs for, 
+
 * linux-64 (x86)
 * osx-64 (x86, intel based macs)
+
 while we do not have continuos integration we have validated MC/DC on other systems.
 
 To run the regression tests locally, navigate to ``\MCDC\tests\regression`` and run,
 
 .. code-block:: sh
+
+
     python run.py <OPTION_FLAG(s)>
 
+
 and all the tests will run. Various option ``OPTION_FLAG`` are accepted to control the tests ran,
 
-* Run a specific test (with wildcard `*` support): ``--name=<test_name>`` 
+* Run a specific test (with wildcard ``*`` support): ``--name=<test_name>`` 
 * Run in Numba mode: ``--mode=numba``
-* Run in multiple MPI ranks (currently support `mpiexec` and `srun`): ``--mpiexec=<number of ranks>``
+* Run in multiple MPI ranks (currently support ``mpiexec`` and ``srun``): ``--mpiexec=<number of ranks>``
 
 Note that flags can be combined. To add a new test:
 
@@ -63,21 +71,33 @@ Note that flags can be combined. To add a new test:
 
 When adding a new hardware backend a new instantiation of the test suit should be made.
 This is done with github actions. 
-See the (.github/workflows) for examples.
+See the (``.github/workflows``) for examples.
 
 If a new simulation type is added (e.g. quasi montecarlo w/ davidson's method, residual monte carlo, intrusive uq) more regression tests should be added with your PR.
 If you are wondering accommodations.
 
 
--------------
-Documentation
--------------
+--------------------
+Adding Documentation
+--------------------
 
 
 It's not everything it needs to be but we are trying!
 If your contribution changes the behavior of the input deck, instillation process, or testing infrastructure your contribution must include alteration to this documentaiton.
 That can be done by editing the RST files in ``/MCDC/docs/source/<FILENAME>.rst``.
 
+To add a new page to the documentation,
+
+#. Add a new file for example ``<FILE_NAME>.rst``
+#. Add the necessary file header (for example this file is: ``.. _contributions:``)
+#. Add ``<FILE_NAME>`` (without file extension to the ``.. toctree::`` section of ``index.rst``)
+#. Write your contributions using ``.rst`` format (see this `cheat sheet <https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst>`_)
+
+To build changes you've made locally before committing,
+
+#. Install dependencies (we recommend: ``conda install sphinx`` and ``pip install furo``). Note that these dependencies are not installed as a part of base MC/DC
+#. Run ``make html`` to compile
+#. Then launch ``build/html/index.html`` with your browser of choice
 
 -------------
 Pull Requests

docs/source/index.rst

@@ -13,10 +13,14 @@ Monte Carlo neutron transport software in active development
 by the `Center for Exascale Monte Carlo Neutron Transport <https://cement-psaap.github.io/>`_ (CEMeNT).
 
 .. note::
+
+
    The project is in the early stages of *very* active development,
    not even an alpha release! 
 
+
 MC/DC is machine portable and is validated to run on:
+
 * linux-64 (x86)
 * osx-64 (x86, intel based macs)
 * osx-arm64 (apple silicon based macs)
@@ -26,6 +30,7 @@ MC/DC is machine portable and is validated to run on:
 * win-64 (runs but not recommend!)
 
 
+
 .. only:: html
 
    --------
@@ -36,7 +41,7 @@ MC/DC is machine portable and is validated to run on:
    :maxdepth: 1
 
    install
-   contributions
+   contribution
    pythonapi/index
 
 
@@ -46,3 +51,11 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
+
+
+To build the docs
+=================
+
+#. Install dependencies (we recommend: ``conda install sphinx`` and ``pip install furo``). Note that these dependencies are not installed as a part of base MC/DC
+#. Run ``make html`` to compile
+#. Then launch ``build/html/index.html`` with your browser of choice

docs/source/install.rst

@@ -86,9 +86,9 @@ On local machines, mpi4py will be installed using conda,
 
 To confirm that everything is properly installed, execute ``pytest`` from the MCDC directory. 
 
-------------------------------------
+-------------------------------------
 Configuring Continuous Energy Library
-------------------------------------
+-------------------------------------
 
 MC/DC has continuous energy transport capabilities.
 We provide the library and easy install to members of CEMeNT and other close developers.