Release 1.0 Documentation

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = ../docs
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/css/custom.css

@@ -0,0 +1,14 @@
+/* reduce the size of the main text */
+p {
+    font-size: 0.95rem;
+}
+
+h1, h2, h3, h4, h5, h6 {
+    font-weight: 500;
+}
+
+.sidebar-brand-text {
+    font-size: 1rem;
+    font-weight: 500;
+    margin: auto;
+}

docs/_templates/sidebar/variant-selector.html

@@ -0,0 +1,15 @@
+<div class="sidebar-tree">
+    <ul>
+    <li class="toctree-l1 has-children"><a class="reference internal" href="">Versions</a>
+        <input class="toctree-checkbox" id="toctree-checkbox-version" name="toctree-checkbox-version" role="switch" type="checkbox"/>
+        <label for="toctree-checkbox-version"><div class="visually-hidden">Toggle navigation of Versions</div>
+            <i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i>
+        </label>
+        <ul>
+        {% for version in versions %}
+            <li class="toctree-l2"><a class="reference internal" href="{{ pathto('/'.join(['..', version, pagename])) }}">{{ version }}</a></li>
+        {% endfor %}
+        </ul>
+    </li>
+    </ul>
+</div>

docs/api_reference/index.rst

@@ -0,0 +1,13 @@
+API Reference
+=============
+
+TODO: Briefly describe the organization of the API reference
+
+TODO: Add more subpackages / modules
+
+.. toctree::
+   :glob:
+
+   onemod.main
+   onemod.pipeline
+   onemod.stage

docs/api_reference/onemod.main.rst

@@ -0,0 +1,13 @@
+onemod.main
+===========
+
+.. automodule:: onemod.main
+    :members: load_pipeline, load_stage, evaluate
+
+TODO: Update docstrings
+
+..
+   These functions are in the main.py module, but some functions
+   (load_pipeline and load_stage) can also be imported via
+   from onemod import load_pipeline. How should this be reflected in
+   the documentation?

docs/api_reference/onemod.pipeline.rst

@@ -0,0 +1,11 @@
+onemod.pipeline
+===============
+
+.. autoclass:: onemod.pipeline.Pipeline
+    :members: from_json, to_json, add_stages, add_stage, build, run, fit, predict
+
+TODO: Update docstrings
+
+..
+  Which methods do we include in the API? Some are only relevant for
+  developers

docs/api_reference/onemod.stage.rst

@@ -0,0 +1,16 @@
+onemod.stage
+============
+
+.. autoclass:: onemod.stage.base.Stage
+   :members:
+   :exclude-members: model_config, model_post_init, validate_build, validate_run, validate_outputs, get_field
+
+.. autoclass:: onemod.stage.base.ModelStage
+   :members:
+   :exclude-members: model_config, model_post_init, apply_stage_specific_config
+
+TODO: Update docstrings
+
+..
+   How do we inherit methods from Stage into ModelStage?
+   Maybe don't worry about it since we are going to merge them anyway

docs/conf.py

@@ -1,22 +1,104 @@
-# General configuration
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.autosectionlabel"]
-autoapi_dirs = ["../"]
-# templates_path = ['_templates']
-source_suffix = ".rst"
-master_doc = "index"
-project = "OneMod"
-copyright = "2022-, University of Washington"
-author = "Mathematical Sciences and Computational Algorithms"
-language = "en"
-todo_include_todos = True
-autoclass_content = "init"
-pygments_style = "sphinx"
-
-# HTML output options
-html_theme = "furo"
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath("."))
+import datetime
+
+import tomllib
+
+with open("../pyproject.toml", "rb") as f:
+    about = tomllib.load(f)["project"]
+
+
+# -- Project information -----------------------------------------------------
+
+project = about["name"]
+author = ", ".join([info["name"] for info in about["authors"]])
+copyright = f"2022-{datetime.datetime.today().year}, {author}"
+
 
+# The full version, including alpha/beta/rc tags
+version = about["version"]
+
+
+# -- 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.autosectionlabel",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+]
+autodoc_typehints = "description"
+autodoc_member_order = "bysource"
+autodoc_type_aliases = {
+    "ArrayLike": "ArrayLike",
+    "NDArray": "NDArray",
+    "DataFrame": "DataFrame",
+}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "furo"
 
-# Additional configurations
-intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
-graphviz_output_format = "svg"
-suppress_warnings = ["autosectionlabel.*"]
+# 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_css_files = ["css/custom.css"]
+html_title = f"{project} {version}"
+html_theme_options = {
+    "sidebar_hide_name": False,
+    "light_logo": "logo/logo-outline-black.svg",
+    "dark_logo": "logo/logo-outline-white.svg",
+    "light_css_variables": {
+        "color-brand-primary": "#008080",
+        "color-brand-content": "#008080",
+        "color-problematic": "#BF5844",
+        "color-background-secondary": "#F8F8F8",
+        "color-admonition-title--note": "#008080",
+        "color-admonition-title-background--note": "#00808033",
+    },
+    "dark_css_variables": {
+        "color-brand-primary": "#6FD8D1",
+        "color-brand-content": "#6FD8D1",
+        "color-problematic": "#FA9F50",
+        "color-background-secondary": "#202020",
+        "color-admonition-title--note": "#6FD8D1",
+        "color-admonition-title-background--note": "#6FD8D133",
+    },
+}
+# get versions
+with open("meta.toml", "rb") as f:
+    versions = tomllib.load(f)["versions"]
+html_context = {"versions": versions}