Start documentation

.github/workflows/build_docs.yml

@@ -0,0 +1,32 @@
+name: Build docs
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        python-version: [ 3.11 ]
+        os: [ ubuntu-latest ]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install .[docs]
+
+      - name: Upload docs
+        run: |
+          mkdocs build  # twice, see https://github.com/patrick-kidger/pytkdocs_tweaks
+          mkdocs gh-deploy --force

.gitignore

@@ -23,3 +23,7 @@ poetry.lock
 
 # PyCharm
 .idea
+
+# Documentation
+.all_objects.cache
+site/

bayesnf/bayesnf/models.py

@@ -123,15 +123,22 @@ def make_likelihood_model(
 
   See also https://en.wikipedia.org/wiki/Negative_binomial_distribution, in
   particular the section on Alternative parameterizations, which defines:
+
+  ```
   probs = mean / variance
   total_count = mean^2 / (variance - mean)
-  so that variance = mean + mean^2 / total_count
-  and thus total_count = 1 / shape
+  ```
+
+  so that `variance = mean + mean^2 / total_count`
+  and thus `total_count = 1 / shape`.
+
+  From this we get the parameters passed to `tfd.NegativeBinomial` below:
 
-  From this we get the parameters passed to tfd.NegativeBinomial below:
+  ```
   total_count = 1 / shape
   probs = mean / (mean + mean^2 * shape)
         = 1 / (1 + mean * shape)
+  ```
 
   For zero inflation we follow ideas from https://arxiv.org/pdf/2010.09647.pdf
 

bayesnf/bayesnf/spatiotemporal.py

@@ -71,7 +71,7 @@ def seasonalities_to_array(
     freq: Frequency of the data.
 
   Raises:
-    TypeError if the seasonality is less than or equal to 1
+    TypeError: If the seasonality is less than or equal to 1.
 
   Returns:
     Array of floats greater than 1, representing seasonalities.

docs/_static/custom.css

@@ -0,0 +1,149 @@
+/* Forked from
+/* https://github.com/patrick-kidger/equinox/blob/main/docs/_static/custom_css.css
+/* Emphasise sections of nav on left hand side */
+
+nav.md-nav {
+    padding-left: 5px;
+  }
+
+  nav.md-nav--secondary {
+      border-left: revert !important;
+  }
+
+  .md-nav__title {
+    font-size: 0.9rem;
+  }
+
+  .md-nav__item--section > .md-nav__link {
+    font-size: 0.9rem;
+  }
+
+  /* Indent autogenerated documentation */
+
+  div.doc-contents {
+    padding-left: 25px;
+    border-left: 4px solid rgba(230, 230, 230);
+  }
+
+  /* Increase visibility of splitters "---" */
+
+  [data-md-color-scheme="default"] .md-typeset hr {
+      border-bottom-color: rgb(0, 0, 0);
+      border-bottom-width: 1pt;
+  }
+
+  [data-md-color-scheme="slate"] .md-typeset hr {
+      border-bottom-color: rgb(230, 230, 230);
+  }
+
+  /* More space at the bottom of the page */
+
+  .md-main__inner {
+    margin-bottom: 1.5rem;
+  }
+
+  /* Remove prev/next footer buttons */
+
+  .md-footer__inner {
+      display: none;
+  }
+
+  /* Change font sizes */
+
+  html {
+      /* Decrease font size for overall webpage
+         Down from 137.5% which is the Material default */
+      font-size: 110%;
+  }
+
+  .md-typeset .admonition {
+      /* Increase font size in admonitions */
+      font-size: 100% !important;
+  }
+
+  .md-typeset details {
+      /* Increase font size in details */
+      font-size: 100% !important;
+  }
+
+  .md-typeset h1 {
+      font-size: 1.6rem;
+  }
+
+  .md-typeset h2 {
+      font-size: 1.5rem;
+  }
+
+  .md-typeset h3 {
+      font-size: 1.3rem;
+  }
+
+  .md-typeset h4 {
+      font-size: 1.1rem;
+  }
+
+  .md-typeset h5 {
+      font-size: 0.9rem;
+  }
+
+  .md-typeset h6 {
+      font-size: 0.8rem;
+  }
+
+  /* Bugfix: remove the superfluous parts generated when doing:
+
+  ??? Blah
+
+      ::: library.something
+  */
+
+  .md-typeset details .mkdocstrings > h4 {
+      display: none;
+  }
+
+  .md-typeset details .mkdocstrings > h5 {
+      display: none;
+  }
+
+  /* Change default colours for <a> tags */
+
+  [data-md-color-scheme="default"] {
+      --md-typeset-a-color: rgb(0, 189, 164) !important;
+  }
+  [data-md-color-scheme="slate"] {
+      --md-typeset-a-color: rgb(0, 189, 164) !important;
+  }
+
+  /* Highlight functions, classes etc. type signatures. Really helps to make clear where
+     one item ends and another begins. */
+
+  [data-md-color-scheme="default"] {
+      --doc-heading-color: #DDD;
+      --doc-heading-border-color: #CCC;
+      --doc-heading-color-alt: #F0F0F0;
+  }
+  [data-md-color-scheme="slate"] {
+      --doc-heading-color: rgb(25,25,33);
+      --doc-heading-border-color: rgb(25,25,33);
+      --doc-heading-color-alt: rgb(33,33,44);
+      --md-code-bg-color: rgb(38,38,50);
+  }
+
+  h4.doc-heading {
+      /* NOT var(--md-code-bg-color) as that's not visually distinct from other code blocks.*/
+      background-color: var(--doc-heading-color);
+      border: solid var(--doc-heading-border-color);
+      border-width: 1.5pt;
+      border-radius: 2pt;
+      padding: 0pt 5pt 2pt 5pt;
+  }
+  h5.doc-heading, h6.heading {
+      background-color: var(--doc-heading-color-alt);
+      border-radius: 2pt;
+      padding: 0pt 5pt 2pt 5pt;
+  }
+
+  /* Make errors in notebooks have scrolling */
+  .output_error > pre {
+      overflow: auto;
+  }

docs/api/evaluate.md

@@ -0,0 +1 @@
+::: bayesnf.evaluate

docs/api/inference.md

@@ -0,0 +1 @@
+::: bayesnf.inference

docs/api/models.md

@@ -0,0 +1 @@
+::: bayesnf.models

docs/api/spatiotemporal.md

@@ -0,0 +1 @@
+::: bayesnf.spatiotemporal

docs/index.md

@@ -0,0 +1 @@
+--8<-- "README.md"

mkdocs.yml

@@ -0,0 +1,89 @@
+theme:
+    name: material
+    features:
+        - navigation.sections  # Sections are included in the navigation on the left.
+        - navigation.expand  # Expand collapsible sections by default
+        - header.autohide  # header disappears as you scroll
+    palette:
+        # Light mode / dark mode
+        # We deliberately don't automatically use `media` to check a user's preferences. We default to light mode as
+        # (a) it looks more professional, and (b) is more obvious about the fact that it offers a (dark mode) toggle.
+        - scheme: default
+          primary: white
+          accent: amber
+          toggle:
+             icon: material/weather-night
+             name: Switch to dark mode
+        - scheme: slate
+          primary: black
+          accent: amber
+          toggle:
+             icon: material/weather-sunny
+             name: Switch to light mode
+    icon:
+        repo: fontawesome/brands/github  # GitHub logo in top right
+
+
+site_name: bayesnf
+site_description: The documentation for the bayesnf software library.
+site_author: Colin Carroll
+site_url: https://google.github.io/bayesnf
+
+repo_url: https://github.com/google/bayesnf
+repo_name: google/bayesnf
+edit_uri: ""  # No edit button, as some of our pages are in /docs and some in /examples via symlink, so it's impossible for them all to be accurate
+
+strict: true  # Don't allow warnings during the build process
+
+extra_javascript:
+    # The below three make MathJax work, see https://squidfunk.github.io/mkdocs-material/reference/mathjax/
+    - _static/mathjax.js
+    - https://polyfill.io/v3/polyfill.min.js?features=es6
+    - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+
+extra_css:
+    - _static/custom.css
+
+markdown_extensions:
+    - pymdownx.arithmatex:  # Render LaTeX via MathJax
+        generic: true
+    - pymdownx.snippets  # Allowing hidden expandable regions denoted by ???
+    - pymdownx.superfences  # Seems to enable syntax highlighting when used with the Material theme.
+    - pymdownx.details  # Allowing hidden expandable regions denoted by ???
+    - admonition
+    - toc:
+        permalink: "¤"  # Adds a clickable permalink to each section heading
+        toc_depth: 4
+
+plugins:
+    - search  # default search plugin; needs manually re-enabling when using any other plugins
+    - autorefs  # Cross-links to headings
+    - mkdocstrings:
+        default_handler: python
+        handlers:
+            python:
+                setup_commands:
+                    - import pytkdocs_tweaks
+                    - pytkdocs_tweaks.main()
+                    - import jaxtyping
+                    - jaxtyping.set_array_name_format("array")
+                    - import jax
+                    - jax.ShapeDtypeStruct.__module__ = "jax"
+                    - jax.core.ClosedJaxpr.__module__ = "jax.core"
+
+                rendering:
+                    # show_root_heading: true  # actually display anything at all...
+                    show_root_full_path: true  # display "diffrax.asdf" not just "asdf"
+                    show_if_no_docstring: false
+                    show_signature_annotations: true
+                    show_source: false  # don't include source code
+                    members_order: source  # order methods according to their order of definition in the source code, not alphabetical order
+                    heading_level: 4
+
+nav:
+    - 'index.md'
+    - Reference:
+          - 'api/models.md'
+          - 'api/spatiotemporal.md'
+          - 'api/inference.md'
+          - 'api/evaluate.md'

pyproject.toml

@@ -44,6 +44,20 @@ dev = [
     "pyink",
 ]
 
+docs = [
+    # Latest versions at time of writing.
+    "mkdocs==1.3.0",            # Main documentation generator.
+    "mkdocs-material==7.3.6",   # Theme
+    "pymdown-extensions==9.4",  # Markdown extensions e.g. to handle LaTeX.
+    "mkdocstrings==0.17.0",     # Autogenerate documentation from docstrings.
+    "mknotebooks==0.7.1",       # Turn Jupyter Lab notebooks into webpages.
+    "pytkdocs_tweaks==0.0.8",   # Tweaks mkdocstrings to improve various aspects
+    "jinja2==3.0.3",            # Older version. After 3.1.0 seems to be incompatible with current versions of mkdocstrings.
+    "nbconvert==6.5.0",        # | Older verson to avoid error
+    "nbformat==5.4.0",          # |
+    "pygments==2.14.0"
+]
+
 [tool.pyink]
 # Formatting configuration to follow Google style-guide
 line-length = 80