docs(python): add more autodoc things and some URL fixes

python/hooks/post_gen_project.py

@@ -1,6 +1,8 @@
 """Provide hooks to run after project is generated."""
+from pathlib import Path
 import shutil
 
 
 if not {{ cookiecutter.add_docs }}:
     shutil.rmtree("docs")
+    Path(".readthedocs.yaml").unlink()

python/{{cookiecutter.project_slug}}/.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: "ubuntu-20.04"
+  tools:
+    python: "3.11"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
+sphinx:
+  configuration: docs/source/conf.py

python/{{cookiecutter.project_slug}}/README.md

@@ -3,12 +3,18 @@
 [![image](https://img.shields.io/pypi/v/{{ cookiecutter.project_slug }}.svg)](https://pypi.python.org/pypi/{{ cookiecutter.project_slug }})
 [![image](https://img.shields.io/pypi/l/{{ cookiecutter.project_slug }}.svg)](https://pypi.python.org/pypi/{{ cookiecutter.project_slug }})
 [![image](https://img.shields.io/pypi/pyversions/{{ cookiecutter.project_slug }}.svg)](https://pypi.python.org/pypi/{{ cookiecutter.project_slug }})
-[![Actions status](https://github.com/{{ cookiecutter.org }}/{{ cookiecutter.project_slug }}/workflows/CI/badge.svg)](https://github.com/{{ cookiecutter.org }}/{{ cookiecutter.project_slug }}/actions)
+[![Actions status](https://github.com/{{ cookiecutter.org }}/{{ cookiecutter.project_slug }}/workflows/checks.yaml/badge.svg)](https://github.com/{{ cookiecutter.org }}/{{ cookiecutter.project_slug }}/actions/checks.yaml)
 
 <!-- description -->
 {{ cookiecutter.description }}
 <!-- /description -->
 
+{% if cookiecutter.add_docs %}---
+
+**[Documentation](https://{{ cookiecutter.project_slug }}.readthedocs.io/stable/)** · [Installation](https://{{ cookiecutter.project_slug }}.readthedocs.io/stable/install.html) · [Usage](https://{{ cookiecutter.project_slug }}.readthedocs.io/stable/usage.html) · [API reference](https://{{ cookiecutter.project_slug }}.readthedocs.io/stable/reference/index.html){% endif %}
+
+---
+
 ## Installation
 
 Install from [PyPI](https://pypi.org/project/{{ cookiecutter.project_slug }}/):
@@ -17,6 +23,12 @@ Install from [PyPI](https://pypi.org/project/{{ cookiecutter.project_slug }}/):
 python3 -m pip install {{ cookiecutter.project_slug }}
 ```
 
+---{% if cookiecutter.add_docs %}
+
+## Feedback and contributing
+
+We welcome bug reports, feature requests, and code contributions from users and interested collaborators. The [documentation](https://{{ cookiecutter.project_slug }}.readthedocs.io/latest/contributing.html) contains guidance for submitting feedback and contributing new code.{% else %}
+
 ## Development
 
 Clone the repo and create a virtual environment:
@@ -45,4 +57,4 @@ Run tests with `pytest`:
 
 ```shell
 pytest
-```
+```{% endif %}

python/{{cookiecutter.project_slug}}/docs/source/_templates/module_summary.rst

@@ -0,0 +1,7 @@
+{{ "{{ fullname | underline }}" }}
+
+.. automodule:: {{ "{{ fullname }}" }}
+   :members:
+   :undoc-members:
+   :special-members: __init__
+   :exclude-members: model_fields, model_config

python/{{cookiecutter.project_slug}}/docs/source/conf.py

@@ -19,6 +19,7 @@
     "sphinx_autodoc_typehints",
     "sphinx.ext.linkcode",
     "sphinx_copybutton",
+    "sphinx.ext.autosummary",
     "sphinx_github_changelog",
 ]
 
@@ -52,10 +53,10 @@
     ],
 }
 # -- autodoc things ----------------------------------------------------------
-import os  # noqa: E402
-import sys  # noqa: E402
+import os
+import sys
 
-sys.path.insert(0, os.path.abspath("../../{{ cookiecutter.project_slug }}"))
+sys.path.insert(0, os.path.abspath("../../"))
 autodoc_preserve_defaults = True
 
 # -- get version -------------------------------------------------------------
@@ -70,7 +71,7 @@ def linkcode_resolve(domain, info):
     if not info["module"]:
         return None
     filename = info["module"].replace(".", "/")
-    return f"https://github.com/{{ cookiecutter.org }}/{{ cookiecutter.repo }}/blob/main/{filename}.py"
+    return f"https://github.com/{{ cookiecutter.org }}/{{ cookiecutter.repo }}/blob/main/src/{filename}.py"
 
 
 # -- code block style --------------------------------------------------------

python/{{cookiecutter.project_slug}}/docs/source/contributing.rst

@@ -1,3 +1,5 @@
+.. _contributing:
+
 Contributing
 ============
 
@@ -46,7 +48,7 @@ Tests are executed with `pytest <https://docs.pytest.org/en/7.1.x/getting-starte
 Documentation
 -------------
 
-The documentation is built with Sphinx, which is included as part of the ``docs`` dependency group. Navigate to the `docs/` subdirectory and use `make` to build the HTML version: ::
+The documentation is built with Sphinx, which is included as part of the ``docs`` dependency group. Navigate to the ``docs/`` subdirectory and use ``make`` to build the HTML version: ::
 
     cd docs
     make html

python/{{cookiecutter.project_slug}}/docs/source/index.rst

@@ -23,6 +23,8 @@
    :maxdepth: 2
 
     Installation<install>
+    Usage<usage>
+    API Reference<reference/index>
     Changelog<changelog>
     Contributing<contributing>
     License<license>

python/{{cookiecutter.project_slug}}/docs/source/install.rst

@@ -1,6 +1,8 @@
+.. _install:
+
 Installation
 ============
 
-Install from `PyPI <https://pypi.org/project/{{ cookiecutter.project_slug }}/`_:
+Install from `PyPI <https://pypi.org/project/{{ cookiecutter.project_slug }}/>`_:
 
     pip install {{ cookiecutter.project_slug }}

python/{{cookiecutter.project_slug}}/docs/source/reference/index.rst

@@ -0,0 +1,14 @@
+.. _api_reference:
+
+API Reference
+=============
+
+Core Modules
+------------
+
+.. autosummary::
+   :nosignatures:
+   :toctree: api/
+   :template: module_summary.rst
+
+   {{ cookiecutter.project_slug }}

python/{{cookiecutter.project_slug}}/docs/source/usage.rst

@@ -0,0 +1,4 @@
+.. _usage:
+
+Usage
+=====

readthedocs_setup.md

@@ -0,0 +1,27 @@
+# readthedocs setup notes
+
+> I am not 100% on the best way to set up automation rules for us. For many of our repos, it might be better just to set a single rule that catches every new GitHub release and sets it as default.
+
+* Settings
+  * Programming Language: `Python`
+* Advanced Settings
+  * Default version: `Stable` (ideally)
+  * Versioning scheme: `Multiple versions without translation`
+  * Build pull requests for this project
+* Integrations
+  * GitHub Incoming Webhook
+* Environment variables
+  * `SPHINX_GITHUB_CHANGELOG_TOKEN`: provide a read-only fine-grained github token (https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#fine-grained-personal-access-tokens). I have an active one. It'll require renewal at least every 12 months.
+* Automation rules
+  * Stable release rule
+    * Match: `Custom match`
+    * Custom match: a pattern for latest stable release
+    * Version type: `Tag`
+    * Action: `Set version as default`
+  * Dev version release rule
+    * Match: `Custom match`
+    * Custom match: a pattern for a dev release
+    * Version type: `Tag`
+    * Action: `Activate version`
+
+Also make sure to add other lab members, and especially Alex, as collaborators.