Merge pull request #179 from yardasol/basic-docs

Basic docpages
arfc · Apr 19, 2023 · 7a14dd9 · 7a14dd9
2 parents b20311a + 8a8505e
commit 7a14dd9
Show file tree

Hide file tree

Showing 51 changed files with 1,505 additions and 310 deletions.
diff --git a/doc/Makefile b/doc/Makefile
@@ -48,6 +48,7 @@ help:
 
 clean:
 	rm -rf $(BUILDDIR)/*
+	rm -r api/generated
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

diff --git a/doc/_templates/myclass.rst b/doc/_templates/myclass.rst
@@ -0,0 +1,7 @@
+{{ fullname }}
+{{ underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+    :members:
diff --git a/doc/_templates/myfunction.rst b/doc/_templates/myfunction.rst
@@ -0,0 +1,6 @@
+{{ fullname }}
+{{ underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}
diff --git a/doc/api/app.rst b/doc/api/app.rst
@@ -0,0 +1,17 @@
+:mod:`saltproc.app`
+###################
+
+``app.py`` contains all the functions needed to actually run the code.
+
+Functions
+---------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myfunction.rst
+
+   app.run
+   app.read_main_input
+   app.reprocess_materials
+   app.refill_materials
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -0,0 +1,52 @@
+SaltProc API
+=============
+
+Depeletion code interfaces
+--------------------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myclass.rst
+
+   saltproc.Depcode
+   saltproc.SerpentDepcode
+   saltproc.OpenMCDepcode
+
+Reprocessing
+------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myclass.rst
+
+   saltproc.Materialflow
+   saltproc.Process
+   saltproc.Sparger
+   saltproc.Separator
+
+Running the simulation
+----------------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   app
+
+Results
+-------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myclass.rst
+
+   saltproc.Simulation
+
+
+This is automatically generated API documentation from SaltProc source files.
+
+Click the  "modules" (:ref:`modindex`) link to browse the modules.
+Or, dive right into the autogenerated :doc:`saltproc` docs.
diff --git a/doc/conf.py b/doc/conf.py
@@ -15,7 +15,6 @@
 import os
 import sys
 import sphinx_rtd_theme
-sys.path.append(os.path.abspath('../'))
 sys.path.append(os.path.abspath('../saltproc'))
 # autopep8 will make a stink about this but
 # we need to have saltproc on ouy syspath
@@ -66,12 +65,12 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinxcontrib.apidoc',
     'sphinx.ext.autodoc',
-    'sphinx.ext.doctest',
+    'sphinx.ext.autosummary',
     'sphinx.ext.intersphinx',
-    'sphinx.ext.todo',
-    'sphinx.ext.coverage',
+    #'sphinx.ext.doctest',
+    #'sphinx.ext.todo',
+    #'sphinx.ext.coverage',
     'sphinx.ext.napoleon',
     'sphinx.ext.mathjax',
     'sphinx.ext.ifconfig',
@@ -80,23 +79,25 @@
     'sphinx-jsonschema']
 
 # apidoc settings
-apidoc_module_dir = '../saltproc/'
-apidoc_output_dir = 'src/'
-apidoc_excluded_paths = []
-apidoc_separate_modules = True
+#apidoc_module_dir = '../saltproc/'
+#apidoc_output_dir = 'api/'
+#apidoc_excluded_paths = ['openmc_deplete.py',
+#                         'version.py']
+#apidoc_separate_modules = True
 
 # Napoleon settings
-napoleon_google_docstring = False
-napoleon_numpy_docstring = True
-napoleon_include_init_with_doc = True
-napoleon_include_private_with_doc = True
-napoleon_include_special_with_doc = True
-napoleon_use_admonition_for_examples = True
-napoleon_use_admonition_for_notes = True
-napoleon_use_admonition_for_references = True
-napoleon_use_ivar = False
-napoleon_use_param = True
-napoleon_use_rtype = True
+##napoleon_google_docstring = False
+##napoleon_numpy_docstring = True
+##napoleon_include_init_with_doc = True
+##napoleon_include_private_with_doc = True
+##napoleon_include_special_with_doc = True
+##napoleon_use_admonition_for_examples = True
+##napoleon_use_admonition_for_notes = True
+##napoleon_use_admonition_for_references = True
+napoleon_use_ivar = True
+##napoleon_use_param = True
+##napoleon_use_rtype = True
+##add_module_names = False
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -107,6 +108,11 @@
 # source_suffix = ['.rst', '.md']
 source_suffix = '.rst'
 
+
+#####
+autosummary_generate = True
+
+
 # The master toctree document.
 master_doc = 'index'
 
@@ -123,7 +129,8 @@
 exclude_patterns = ['_build']
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+##pygments_style = 'sphinx'
+pygments_style = 'tango'
 
 # If true, keep warnings as "system message" paragraphs in the built documents.
 # keep_warnings = False

diff --git a/doc/devguide/contributing.rst b/doc/devguide/contributing.rst
@@ -1,3 +1,5 @@
+.. _devguide_contributing:
+
 Contributing
 ============
 

diff --git a/doc/devguide/index.rst b/doc/devguide/index.rst
@@ -21,3 +21,5 @@ in this developer's guide that relies on understanding it.
    :maxdepth: 1
 
    contributing
+   style
+   tests
diff --git a/doc/devguide/style.rst b/doc/devguide/style.rst
@@ -0,0 +1,6 @@
+.. _devguide_style:
+
+Style Guide
+===========
+
+Coming soon!
diff --git a/doc/devguide/tests.rst b/doc/devguide/tests.rst
@@ -0,0 +1,6 @@
+.. _devguide_tests:
+
+Test Suite
+==========
+
+Coming soon!
diff --git a/doc/index.rst b/doc/index.rst
@@ -7,21 +7,18 @@ SaltProc
 =========
 
 **SaltProc** is a python package for liquid-fueled nuclear reactor depletion
-calculations. It couples directly with the `Serpent2`_ or `OpenMC`_ Monte Carlo depletion
-software to enable online reprocessing system modeling in depletion
+calculations. It couples directly with depletion-capable transport solvers to enable online reprocessing system modeling in depletion
 calculations.
 
 **SaltProc** welcomes your contributions. It already relies on many libraries
 in the Scientific Python ecosystem including `pyne`_, `numpy`_, `matplotlib`_,
-`networkx`_, and `pydotplus`_.
+`networkx`_, and `pydot`_.
 
-.. _Serpent2: http://montecarlo.vtt.fi
-.. _OpenMC: https://openmc.org/
 .. _pyne: http://pyne.io/
 .. _numpy: http://numpy.org
 .. _matplotlib: http://matplotlib.org
 .. _networkx: http://networkx.github.io
-.. _pydotplus: https://pydotplus.readthedocs.io/
+.. _pydot: https://pypi.org/project/pydot/
 
 
 Documentation
@@ -33,10 +30,12 @@ Documentation
    overview
    installation
    examples
-   src/index
    releasenotes/index
+   methods/index
+   userguide/index
    devguide/index
-   fileformatspec/index
+   api/index
+   io_formats/index
    How to cite <https://github.com/arfc/saltproc/blob/master/CITATION.md>
 
 Indices and tables

diff --git a/doc/fileformatspec/databasefile.rst → doc/io_formats/databasefile.rst b/doc/fileformatspec/databasefile.rst → doc/io_formats/databasefile.rst
@@ -1,3 +1,5 @@
+.. _results_file:
+
 ================
 HDF5 Output File
 ================

diff --git a/doc/fileformatspec/depcode_input.rst → doc/io_formats/depcode_input.rst b/doc/fileformatspec/depcode_input.rst → doc/io_formats/depcode_input.rst
@@ -95,6 +95,9 @@ Serpent-specific properties
   :pattern: 
     ``^(.\\/)*(.*)$``
 
+
+.. _zaid_convention_property:
+
 ``zaid_convention``
 ~~~~~~~~~~~~~~~~~~~
 
@@ -209,7 +212,7 @@ OpenMC-specific properties
     ``string``
 
 
-.. _opemc_depletion_settings_property:
+.. _openmc_depletion_settings_property:
 
 ``depletion_settings``
 ~~~~~~~~~~~~~~~~~~~~~~

diff --git a/doc/fileformatspec/index.rst → doc/io_formats/index.rst b/doc/fileformatspec/index.rst → doc/io_formats/index.rst
@@ -1,9 +1,9 @@
-.. _fileformatspec:
+.. _io_formats:
 
 File Format Specifications
 ==========================
 
-.. _fileformatspect_input_files:
+.. _io_formats_input_files:
 
 Input Files
 -----------
@@ -17,7 +17,7 @@ Input Files
   reactor_input
 
 
-.. _fileformatspec_output_files:
+.. _io_formats_output_files:
 
 Output Files
 ------------

diff --git a/doc/fileformatspec/reactor_input.rst → doc/io_formats/reactor_input.rst b/doc/fileformatspec/reactor_input.rst → doc/io_formats/reactor_input.rst
@@ -103,7 +103,7 @@ Required properties: ``volume``, ``mass_flowrate``, ``power_levels``,
   :default:
     ``stepwise``
 
-.. _timestep_unites_property:
+.. _timestep_units_property:
 
 ``timestep_units``
 ------------------

diff --git a/doc/fileformatspec/saltproc_input.rst → doc/io_formats/saltproc_input.rst b/doc/fileformatspec/saltproc_input.rst → doc/io_formats/saltproc_input.rst
diff --git a/doc/fileformatspec/simulation_input.rst → doc/io_formats/simulation_input.rst b/doc/fileformatspec/simulation_input.rst → doc/io_formats/simulation_input.rst
diff --git a/doc/methods/coupling.rst b/doc/methods/coupling.rst
@@ -0,0 +1,6 @@
+.. _methods_coupling:
+
+Coupling
+========
+
+SaltProc used file-based coupling to interface with external depletion solvers....
diff --git a/doc/methods/geometry_switching.rst b/doc/methods/geometry_switching.rst
@@ -0,0 +1,7 @@
+.. _methods_geometry_switching:
+
+Geometry Switching
+==================
+
+coming soon...
+
diff --git a/doc/methods/index.rst b/doc/methods/index.rst
@@ -0,0 +1,19 @@
+.. _methods:
+
+======================
+Theory and Methodology
+======================
+
+Welcome to the SaltProc theory and methodology guide. Here you'll find details
+about the SaltProc's program flow, design, mathematical background, and more.
+
+.. note:: The SaltProc theory manual is a work in progress. 
+   Information contained within may change, so make sure to check the 
+   release notes for updates!
+
+.. toctree::
+   :maxdepth: 1
+
+   coupling
+   reprocessing
+   geometry_switching
diff --git a/doc/methods/reprocessing.rst b/doc/methods/reprocessing.rst
@@ -0,0 +1,6 @@
+.. _methods_reprocessing:
+
+Reprocessing Methods
+====================
+
+Coming soon!