Sphinx documentation updates

wsp-sag · May 11, 2021 · d85163f · d85163f
1 parent dbad21a
commit d85163f
Show file tree

Hide file tree

Showing 72 changed files with 28,670 additions and 79 deletions.
diff --git a/.gitignore b/.gitignore
@@ -65,7 +65,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+apidoc/_build/
 
 # PyBuilder
 target/
@@ -96,4 +96,4 @@ ENV/
 .idea
 
 # VSCode settings
-.vscode
+.vscode
diff --git a/doc/Makefile → apidoc/Makefile b/doc/Makefile → apidoc/Makefile
diff --git a/doc/conf.py → apidoc/conf.py b/doc/conf.py → apidoc/conf.py
@@ -14,28 +14,38 @@
 import sys
 sys.path.insert(0, os.path.abspath('..'))
 
+# -- Project info setup ------------------------------------------------------
+
+from datetime import datetime
+from pathlib import Path
+from pkg_resources import parse_version
+
+version_ = {}
+with open(Path(__file__).resolve().parent.parent / 'balsa' / 'version.py') as fp:
+    exec(fp.read(), {}, version_)
+version_ = parse_version(version_['__version__'])
 
 # -- Project information -----------------------------------------------------
 
-project = 'balsa'
-copyright = '2019, WSP, Peter Kucirek'
-author = 'WSP, Peter Kucirek'
+project = 'wsp-balsa'
+author = 'WSP Canada Inc.'
+copyright = f'{datetime.today().year}, {author}'
 
 # The short X.Y version
-version = '1.0'
+version = version_.base_version
 
 # The full version, including alpha/beta/rc tags
-release = '1.0'
-
+release = version_.public
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
-    'sphinx.ext.autodoc'
+    'sphinx.ext.githubpages'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -55,9 +65,13 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'pydata_sphinx_theme'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
+
+html_theme_options = {
+    'collapse_navigation': True
+}
diff --git a/doc/index.rst → apidoc/index.rst b/doc/index.rst → apidoc/index.rst
@@ -9,18 +9,9 @@ The import statement for the ``wsp-balsa`` package is as follows:
 
    import balsa
 
-``wsp-balsa`` is published by the Systems Analytics for Policy group inside WSP Canada.
-
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
-
-   modules/balsa.routines
-   modules/balsa.logging
-
-Indices and tables
-==================
+   :maxdepth: 3
+   :caption: Contents
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   routines/index
+   logging/index
diff --git a/doc/modules/balsa.logging.rst → apidoc/logging/index.rst b/doc/modules/balsa.logging.rst → apidoc/logging/index.rst
@@ -1,10 +1,8 @@
+=======
 Logging
 =======
 
 Collection of classes and functions to configuration Python Logger objects, re-purposed to provide detailed status messages during model program execution.
 
-Contents
---------
-
 .. automodule:: balsa.logging
    :members:
diff --git a/doc/make.bat → apidoc/make.bat b/doc/make.bat → apidoc/make.bat
diff --git a/apidoc/routines/general.rst b/apidoc/routines/general.rst
@@ -0,0 +1,6 @@
+=================
+General Utilities
+=================
+
+.. automodule:: balsa.routines.general
+   :members:
diff --git a/apidoc/routines/index.rst b/apidoc/routines/index.rst
@@ -0,0 +1,14 @@
+========
+Routines
+========
+
+A collection of standalone functions for performing various modelling tasks.
+
+.. toctree::
+   :maxdepth: 2
+
+   general
+   io
+   modelling
+   matrices
+   plotting
diff --git a/apidoc/routines/io.rst b/apidoc/routines/io.rst
@@ -0,0 +1,42 @@
+============
+IO Utilities
+============
+
+Routines for reading and writing demand modelling files, particularly matrices and TMG Toolbox network packages.
+
+Matrices
+--------
+
+Common
+~~~~~~
+
+.. automodule:: balsa.routines.io.common
+   :members:
+
+Inro (Emme) format
+~~~~~~~~~~~~~~~~~~
+
+.. automodule:: balsa.routines.io.inro
+   :members:
+
+
+OMX format
+~~~~~~~~~~
+
+The Python library openmatrix already exists, but doesn't provide a lot of interoperability with Pandas. Balsa provides
+wrapper functions that produce Pandas DataFrames and Series directly from OMX files.
+
+.. automodule:: balsa.routines.io.omx
+   :members:
+
+Fortran format
+~~~~~~~~~~~~~~
+
+.. automodule:: balsa.routines.io.fortran
+   :members:
+
+Network Packages (NWP)
+----------------------
+
+.. automodule:: balsa.routines.io.nwp
+   :members:
diff --git a/apidoc/routines/matrices.rst b/apidoc/routines/matrices.rst
@@ -0,0 +1,6 @@
+================
+Matrix Utilities
+================
+
+.. automodule:: balsa.routines.matrices
+   :members:
diff --git a/apidoc/routines/modelling.rst b/apidoc/routines/modelling.rst
@@ -0,0 +1,6 @@
+===================
+Modelling Utilities
+===================
+
+.. automodule:: balsa.routines.modelling
+   :members:
diff --git a/apidoc/routines/plotting.rst b/apidoc/routines/plotting.rst
@@ -0,0 +1,6 @@
+==================
+Plotting Utilities
+==================
+
+.. automodule:: balsa.routines.plotting
+   :members:
diff --git a/balsa/logging.py b/balsa/logging.py
@@ -85,6 +85,7 @@ def tip(self, msg, *args, **kwargs):
 
 
 def init_root(root_name, stream_format=LogFormats.FANCY, log_debug=True):
+    """Initialize a balsa logger"""
     logging.addLevelName(_TIP_LEVEL, 'TIP')
     logging.addLevelName(_REPORT_LEVEL, 'REPORT')
     logging.setLoggerClass(ModelLogger)
@@ -142,12 +143,14 @@ def _prep_fancy_formatter():
 
 
 def get_model_logger(name):
+    """Retrieve a balsa logger"""
     logging.setLoggerClass(ModelLogger)
     return logging.getLogger(name)
 
 
 @contextmanager
 def log_to_file(file_name: str, name, append=False, raw_ascii=False):
+    """A context mananger for collecting and saving logger messages to file"""
     root = logging.getLogger(name)
 
     write_mode = 'a' if append else 'w'

diff --git a/balsa/routines/io/omx.py b/balsa/routines/io/omx.py
@@ -1,11 +1,3 @@
-"""
-OMX format
-==========
-
-The Python library openmatrix already exists, but doesn't provide a lot of interoperability with Pandas. Balsa provides
-wrapper functions that produce Pandas DataFrames and Series directly from OMX files.
-"""
-
 import numpy as np
 import pandas as pd
 from typing import Union, Iterable, Dict

diff --git a/doc/modules/balsa.routines.rst b/doc/modules/balsa.routines.rst
diff --git a/docs/.buildinfo b/docs/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: d163a3190e500cd10d1ae4f8fe918647
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/_sources/index.rst.txt b/docs/_sources/index.rst.txt
@@ -0,0 +1,17 @@
+wsp-balsa: Common modelling tools
+=================================
+
+``wsp-balsa`` is a collection of functions and tools for Python to facilitate travel demand forecasting applications and analyses. It is designed to work the the "scientific stack" of Python, namely NumPy, Pandas, and Matplotlib; which are optimized for speed and usability. The package mostly consists of standalone functions; for input/output, for analysis, etc.; as well as a few lightweight class-based data structures for specific applications.
+
+The import statement for the ``wsp-balsa`` package is as follows:
+
+.. code-block:: python
+
+   import balsa
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents
+
+   routines/index
+   logging/index
diff --git a/docs/_sources/logging/index.rst.txt b/docs/_sources/logging/index.rst.txt
@@ -0,0 +1,8 @@
+=======
+Logging
+=======
+
+Collection of classes and functions to configuration Python Logger objects, re-purposed to provide detailed status messages during model program execution.
+
+.. automodule:: balsa.logging
+   :members:
diff --git a/docs/_sources/routines/general.rst.txt b/docs/_sources/routines/general.rst.txt
@@ -0,0 +1,6 @@
+=================
+General Utilities
+=================
+
+.. automodule:: balsa.routines.general
+   :members:
diff --git a/docs/_sources/routines/index.rst.txt b/docs/_sources/routines/index.rst.txt
@@ -0,0 +1,14 @@
+========
+Routines
+========
+
+A collection of standalone functions for performing various modelling tasks.
+
+.. toctree::
+   :maxdepth: 2
+
+   general
+   io
+   modelling
+   matrices
+   plotting
diff --git a/docs/_sources/routines/io.rst.txt b/docs/_sources/routines/io.rst.txt
@@ -0,0 +1,42 @@
+============
+IO Utilities
+============
+
+Routines for reading and writing demand modelling files, particularly matrices and TMG Toolbox network packages.
+
+Matrices
+--------
+
+Common
+~~~~~~
+
+.. automodule:: balsa.routines.io.common
+   :members:
+
+Inro (Emme) format
+~~~~~~~~~~~~~~~~~~
+
+.. automodule:: balsa.routines.io.inro
+   :members:
+
+
+OMX format
+~~~~~~~~~~
+
+The Python library openmatrix already exists, but doesn't provide a lot of interoperability with Pandas. Balsa provides
+wrapper functions that produce Pandas DataFrames and Series directly from OMX files.
+
+.. automodule:: balsa.routines.io.omx
+   :members:
+
+Fortran format
+~~~~~~~~~~~~~~
+
+.. automodule:: balsa.routines.io.fortran
+   :members:
+
+Network Packages (NWP)
+----------------------
+
+.. automodule:: balsa.routines.io.nwp
+   :members:
diff --git a/docs/_sources/routines/matrices.rst.txt b/docs/_sources/routines/matrices.rst.txt
@@ -0,0 +1,6 @@
+================
+Matrix Utilities
+================
+
+.. automodule:: balsa.routines.matrices
+   :members:
diff --git a/docs/_sources/routines/modelling.rst.txt b/docs/_sources/routines/modelling.rst.txt
@@ -0,0 +1,6 @@
+===================
+Modelling Utilities
+===================
+
+.. automodule:: balsa.routines.modelling
+   :members:
diff --git a/docs/_sources/routines/plotting.rst.txt b/docs/_sources/routines/plotting.rst.txt
@@ -0,0 +1,6 @@
+==================
+Plotting Utilities
+==================
+
+.. automodule:: balsa.routines.plotting
+   :members: