Update autogenerated documentation (#54)

* Update docs dependencies

* Update LICENSE

* Add custom module template and filters

* Add changelog to docs

* Update README and docs index

* Update custom doc templates

* Fix documentation workflow

.github/workflows/documentation.yml

@@ -19,13 +19,31 @@ jobs:
       with:
         python-version: 3.9
 
+    - name: Install poetry
+      uses: snok/install-poetry@v1
+      with:
+        virtualenvs-create: true
+        virtualenvs-in-project: true
+
+    - name: Load cached venv
+      id: cached-poetry-dependencies
+      uses: actions/cache@v3
+      with:
+        path: .venv
+        key: venv-${{ runner.os }}-${{ hashFiles('**/poetry.lock') }}
+
     - name: Install dependencies
+      if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
+      run: |
+        poetry install --no-interaction --no-root
+
+    - name: Install library
       run: |
-        python -m pip install --upgrade pip
-        pip install Sphinx sphinx-rtd-theme sphinx-mdinclude
+        poetry install --no-interaction
 
     - name: Generate documentation with Sphinx
       run: |
+        source .venv/bin/activate
         make docs
         touch docs/_build/html/.nojekyll
 

LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2022, Bagheri Lab
+Copyright (c) 2023, Bagheri Lab
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

Makefile

@@ -21,7 +21,6 @@ build: # run tox tests and lint
 	tox
 
 docs: # generates documentation
-	sphinx-apidoc -o docs/ -f -M -e src/* **/tests/
 	make -C docs html
 
 release:

README.md

@@ -3,3 +3,69 @@
 [![Lint Status](https://github.com/bagherilab/container-collection/workflows/lint/badge.svg)](https://github.com/bagherilab/container-collection/actions?query=workflow%3Alint)
 [![Documentation](https://github.com/bagherilab/container-collection/workflows/documentation/badge.svg)](https://bagherilab.github.io/container-collection/)
 [![Code style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+Collection of tasks for running containerized models.
+Designed to be used both in [Prefect](https://docs.prefect.io/latest/) workflows and as modular, useful pieces of code.
+
+# Installation
+
+The collection can be installed using:
+
+```bash
+pip install container-collection
+```
+
+We recommend using [Poetry](https://python-poetry.org/) to manage and install dependencies.
+To install into your Poetry project, use:
+
+```bash
+poetry add container-collection
+```
+
+# Usage
+
+## Prefect workflows
+
+All tasks in this collection are wrapped in a Prefect `@task` decorator, and can be used directly in a Prefect `@flow`.
+Running tasks within a [Prefect](https://docs.prefect.io/latest/) flow enables you to take advantage of features such as automatically retrying failed tasks, monitoring workflow states, running tasks concurrently, deploying and scheduling flows, and more.
+
+```python
+from prefect import flow
+from container_collection.<module_name> import <task_name>
+
+@flow
+def run_flow():
+    <task_name>()
+
+if __name__ == "__main__":
+    run_flow()
+```
+
+See [cell-abm-pipeline](https://github.com/allen-cell-animated/cell-abm-pipeline) for examples of using tasks from different collections to build a pipeline for simulating and analyzing agent-based model data.
+
+## Individual tasks
+
+Not all use cases require a full workflow.
+Tasks in this collection can be used without the Prefect `@task` decorator by simply importing directly from the module:
+
+```python
+from container_collection.<module_name>.<task_name> import <task_name>
+
+def main():
+    <task_name>()
+
+if __name__ == "__main__":
+    main()
+```
+
+or using the `.fn()` method:
+
+```python
+from container_collection.<module_name> import <task_name>
+
+def main():
+    <task_name>.fn()
+
+if __name__ == "__main__":
+    main()
+```

docs/_templates/custom_module.rst

@@ -0,0 +1,49 @@
+{{ objname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+    :members:
+    :undoc-members:
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/_templates/custom_summary.rst

@@ -0,0 +1,64 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+    :members:
+    :undoc-members:
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+
+.. currentmodule:: {{module | custom_module }}
+
+.. autosummary::
+   :toctree:
+   :template: custom_module.rst
+   :recursive:
+{% for item in modules %}
+   {{ item | custom_fullname }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/changelog.rst

@@ -0,0 +1,6 @@
+---------
+Changelog
+---------
+
+.. include:: ../CHANGELOG.md
+   :parser: myst_parser.sphinx_

docs/conf.py

@@ -10,20 +10,21 @@
 # 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 importlib.metadata
 import os
 import sys
-sys.path.insert(0, os.path.abspath('../src'))
+from datetime import datetime
 
-import sphinx_rtd_theme
+from sphinx.ext.autosummary.generate import AutosummaryRenderer
 
-# -- Project information -----------------------------------------------------
+sys.path.insert(0, os.path.abspath("../src"))
 
-project = 'Container collection'
-copyright = 'YYYY, AUTHOR_NAME'
-author = 'AUTHOR_NAME'
+# -- Project information -----------------------------------------------------
 
-# The full version, including alpha/beta/rc tags
-release = 'VERSION NUMBER X.X.X'
+project = "Container Collection"
+author = importlib.metadata.metadata("container-collection")["Author"]
+copyright = f"{datetime.now().year}, {author}, Bagheri Lab"
+release = importlib.metadata.version("container-collection")
 
 # -- General configuration ---------------------------------------------------
 
@@ -32,39 +33,62 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
-    "sphinx_rtd_theme",
-    "sphinx_mdinclude",
+    "myst_parser",
+    "sphinx_copybutton",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+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']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # Decides whether module names are prepended to all object names.
 add_module_names = False
 
 # Default options for autodoc directives.
 autodoc_default_options = {
-    'member-order': 'bysource',
-    'undoc-members': True,
+    "member-order": "bysource",
+    "undoc-members": True,
 }
 
-# List of modules to be mocked up. Useful when some external dependencies are not met at build time and break the building process.
+# List of modules to be mocked up. Useful when some external dependencies are
+# not met at build time and break the building process.
 autodoc_mock_imports = []
 
+# Controls how to represent typehints.
+autodoc_typehints = "description"
+
 # -- 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 = 'sphinx_rtd_theme'
+html_theme = "furo"
+
+# The name for this set of Sphinx documents.
+html_title = f"<strong>{project}</strong> <br />{release}"
+
+# -- Patch custom template filters -------------------------------------------
+
+
+def custom_fullname_filter(fullname):
+    return ".".join(fullname.split(".")[1:])
+
+
+def custom_module_filter(module):
+    return module.split(".")[0]
+
+
+def patch_init(self, app):
+    AutosummaryRenderer.__original_init__(self, app)
+    self.env.filters["custom_fullname"] = custom_fullname_filter
+    self.env.filters["custom_module"] = custom_module_filter
+
 
-# 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']
+AutosummaryRenderer.__original_init__ = AutosummaryRenderer.__init__
+AutosummaryRenderer.__init__ = patch_init

docs/index.rst

@@ -1,16 +1,32 @@
+|
+
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
+
+Module reference
+================
+
+.. autosummary::
+   :toctree: _summary
+   :caption: Module reference
+   :template: custom_summary.rst
+   :recursive:
+
+   container_collection.batch
+   container_collection.docker
+   container_collection.fargate
+   container_collection.manifest
+   container_collection.template
+
 .. toctree::
    :hidden:
-   :maxdepth: 1
-   :caption: Contents:
-
-   Overview <self>
-   Package modules <modules>
+   :caption: Development
 
-.. mdinclude:: ../README.md
+   Changelog <changelog>
 
-Indices and tables
-==================
+.. toctree::
+   :hidden:
+   :caption: Project links
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   GitHub <https://github.com/bagherilab/container-collection>
+   PyPI <https://pypi.org/project/container-collection/>