Documentation: Overview methods, ESN modules, & API overhaul (#58)

* actually installing via pip does not work

* methods overview init

* initial distributed docs

* make dense matrices the default.. and fix the kwargs.pop bug

* there shouldnt be a default for boundary

* methods basically done

* standard esn usage overhauled

* lazy usage updated ; normalize data in both

* some little details

* nice printing ... final details done

* cleaned up api presentation

* documented these finally

* some more details

* build docs in PR

* try this

* remove source code from index ; debug docs build workflow

* simplify workflow dramatically

* fix now hidden properties in lazy ; make boundary like overlap.. as documented... and test it

.github/workflows/sphinx.yaml

@@ -0,0 +1,30 @@
+
+name: Build Documentation
+on:
+  pull_request:
+    branches:
+      - "*"
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Cache conda
+        uses: actions/cache@v2
+        env:
+          CACHE_NUMBER: 0
+        with:
+          path: ~/conda_pkgs_dir
+          key: ${{ runner.os }}-conda-${{ env.CACHE_NUMBER }}-${{ hashFiles('docs/environment.yaml') }}
+      - uses: conda-incubator/setup-miniconda@v2
+        with:
+          activate-environment: xesn
+          auto-update-conda: false
+          python-version: 3.11
+          environment-file: docs/environment.yaml
+          use-only-tar-bz2: true # IMPORTANT: This needs to be set for caching to work properly!
+      - name: Build Docs
+        shell: bash -l {0}
+        run: |
+          cd docs ; make html

docs/.gitignore

@@ -1 +1,2 @@
 source/xesn
+generated/

docs/_templates/autosummary/class.rst

@@ -0,0 +1,26 @@
+{{ objname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: Methods
+   .. autosummary::
+      :toctree:
+   {% for item in methods %}
+      {{ name }}.{{ item }}
+   {% endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Attributes
+   .. autosummary::
+   {% for item in attributes %}
+      {{ name }}.{{ item }}
+   {% endfor %}
+   {% endif %}
+   {% endblock %}

docs/api.rst

@@ -1,37 +1,36 @@
-API
-###
+API Reference
+#############
+
+
+ESN Models and Utilities
+------------------------
 
 .. autosummary::
-   xesn.Driver
+   :toctree: generated/
+
    xesn.ESN
    xesn.LazyESN
    xesn.from_zarr
 
-.. autoclass:: xesn.Driver
-   :members:
-
-.. autoclass:: xesn.ESN
-   :members:
-
-.. autoclass:: xesn.LazyESN
-   :members:
+Optimization Tools
+------------------
 
-.. autofunction:: xesn.from_zarr
-
-.. autoclass:: xesn.XData
-   :members:
-
-.. autoclass:: xesn.RandomMatrix
-   :members:
+.. autosummary::
+   :toctree: generated/
 
-.. autoclass:: xesn.SparseRandomMatrix
-   :members:
+   xesn.cost.CostFunction
+   xesn.optim.optimize
+   xesn.optim.transform
+   xesn.optim.inverse_transform
 
-.. autoclass:: xesn.cost.CostFunction
-   :members:
 
-.. autofunction:: xesn.optim.optimize
+Everything Else
+---------------
 
-.. autofunction:: xesn.optim.transform
+.. autosummary::
+   :toctree: generated/
 
-.. autofunction:: xesn.optim.inverse_transform
+   xesn.Driver
+   xesn.RandomMatrix
+   xesn.SparseRandomMatrix
+   xesn.XData

docs/conf.py

@@ -8,10 +8,12 @@
 
 import os
 import sys
+import datetime
 sys.path.insert(0, os.path.abspath("../"))
 
 project = 'xesn'
 copyright = '2023, xesn developers'
+copyright = f"2023-{datetime.datetime.now().year}, xesn developers"
 author = 'xesn developers'
 
 # -- General configuration ---------------------------------------------------
@@ -22,20 +24,32 @@
         "sphinx.ext.autosummary",
         "sphinx.ext.napoleon",
         "nbsphinx",
+        "sphinxcontrib.bibtex",
         ]
 
 numpydoc_show_class_members = False
+napolean_google_docstring = True
+napolean_numpy_docstring = False
 
 templates_path = ['_templates']
 exclude_patterns = []
 
 napoleon_custom_sections = [("Returns", "params_style"),
                             ("Sets Attributes", "params_style"),
+                            ("Assumptions", "notes_style"),
                             ]
 
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'sphinx_book_theme'
 html_static_path = ['_static']
+
+bibtex_bibfiles = ['references.bib']
+bibtex_reference_style = "author_year"
+
+html_theme_options = {
+    "repository_url": "https://github.com/timothyas/xesn",
+    "use_repository_button": True,
+}

docs/environment.yaml

@@ -21,8 +21,9 @@ dependencies:
     - coverage
 # docs stuff
     - sphinx
-    - sphinx_rtd_theme
     - nbsphinx
+    - sphinx-book-theme
+    - sphinxcontrib-bibtex
     - pip
     - pip:
       - smt>=2.0.1