Add support for Read the Docs

claui · claui · commit d0146fc6f28d · 2024-12-05T21:43:29.000+01:00
diff --git a/.editorconfig b/.editorconfig
@@ -26,5 +26,5 @@ trim_trailing_whitespace = false
 [*.py]
 indent_size = 4
 
-[*.yml]
+[*.{yaml,yml}]
 indent_size = 2
diff --git a/.gitattributes b/.gitattributes
@@ -22,4 +22,5 @@
 *.py            text eol=lf
 *.toml          text eol=lf
 *.txt           text eol=lf
+*.yaml          text eol=lf
 *.yml           text eol=lf
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -24,6 +24,7 @@
     "**/?? cookiecutter.pypi_package_name ??/**/*.md": "jinja-md",
     "**/?? cookiecutter.pypi_package_name ??/**/*.py": "jinja-py",
     "**/?? cookiecutter.pypi_package_name ??/**/*.toml": "jinja-toml",
+    "**/?? cookiecutter.pypi_package_name ??/**/*.yaml": "jinja-yaml",
     "**/?? cookiecutter.pypi_package_name ??/**/*.yml": "jinja-yaml",
     "**/?? cookiecutter.pypi_package_name ??/**/PKGBUILD": "jinja-shell",
     "**/hooks/*_gen_project.py": "jinja-py"
diff --git a/README.md b/README.md
@@ -71,7 +71,9 @@ The Cookiecutter template will give you:
 
 - a pytest script and default configuration;
 
-- a `pdoc` setup to generate documentation;
+- a Sphinx setup to generate HTML documentation and a manual page;
+
+- a configuration file for Read the Docs;
 
 - a set of `poe` tasks for running the module scripts, tests and the
   linter (for details, run `poetry run poe tasks`);
diff --git a/{{ cookiecutter.pypi_package_name }}/.editorconfig b/{{ cookiecutter.pypi_package_name }}/.editorconfig
@@ -26,5 +26,5 @@ trim_trailing_whitespace = false
 [*.py]
 indent_size = 4
 
-[*.yml]
+[*.{yaml,yml}]
 indent_size = 2
diff --git a/{{ cookiecutter.pypi_package_name }}/.gitattributes b/{{ cookiecutter.pypi_package_name }}/.gitattributes
@@ -22,4 +22,5 @@
 *.py            text eol=lf
 *.toml          text eol=lf
 *.txt           text eol=lf
+*.yaml          text eol=lf
 *.yml           text eol=lf
diff --git a/{{ cookiecutter.pypi_package_name }}/.github/workflows/ci.yml b/{{ cookiecutter.pypi_package_name }}/.github/workflows/ci.yml
@@ -61,5 +61,5 @@ jobs:
       - name: Run unit tests
         run: poetry run poe tests
 
-      - name: Run man page generator
+      - name: Run man page and HTML documentation generator
         run: poetry run poe doc
diff --git a/{{ cookiecutter.pypi_package_name }}/.gitignore b/{{ cookiecutter.pypi_package_name }}/.gitignore
@@ -6,6 +6,7 @@
 /debian/{{ cookiecutter.pypi_package_name }}.*.debhelper
 /debian/{{ cookiecutter.pypi_package_name }}.substvars
 /dist/
+/doc/sphinx/autoapi/
 /.pc/
 /.venv/
 *.egg-info
diff --git a/{{ cookiecutter.pypi_package_name }}/.readthedocs.yaml b/{{ cookiecutter.pypi_package_name }}/.readthedocs.yaml
@@ -0,0 +1,17 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "{{ cookiecutter.python_version }}"
+
+python:
+  install:
+    - requirements: doc/requirements.txt
+
+sphinx:
+  configuration: doc/sphinx/conf.py
diff --git a/{{ cookiecutter.pypi_package_name }}/CONTRIBUTING.md b/{{ cookiecutter.pypi_package_name }}/CONTRIBUTING.md
@@ -166,13 +166,19 @@ act
 
 ### Generating project documentation
 
-To generate project documentation, run:
+To generate project documentation (HTML and man page), run:
 
 ```shell
 poetry run poe doc
 ```
 
-To open the generated documentation with `man`, run:
+To open the generated HTML documentation in your browser, run:
+
+```shell
+poetry run poe html
+```
+
+To open the generated manual page in your terminal, run:
 
 ```shell
 poetry run poe man
@@ -204,3 +210,11 @@ To check {{ cookiecutter.project_title }}’s dependencies for compatible update
 ```shell
 poetry update --dry-run
 ```
+
+### Updating requirements file for Read the Docs
+
+To update the `doc/requirements.txt` file for Read the Docs, run:
+
+```shell
+poetry export --only doc --output doc/requirements.txt
+```
diff --git a/{{ cookiecutter.pypi_package_name }}/README.md b/{{ cookiecutter.pypi_package_name }}/README.md
@@ -27,7 +27,7 @@ actions by Marketplace verified creators*.
 Then add the following actions to the *Allow specified actions and
 reusable workflows* field:
 
-```plain
+```text
 EndBug/add-and-commit@v9,
 snok/install-poetry@v1,
 softprops/action-gh-release@v1,
@@ -49,6 +49,10 @@ upper right corner to bring up the Repository settings dialog.
 In the *Include in the home page* section, disable Packages but keep
 Releases and Deployments enabled.
 
+Finally, go to the
+[Read the Docs import dashboard](https://app.readthedocs.org/dashboard/import/)
+and import your GitHub project to Read the Docs.
+
 Now that you’ve done everything in this section, delete the section from
 this document.
 
@@ -88,7 +92,13 @@ Direct your favorite
 ```
 
 {% endif -%}
-See [`USAGE.md`](https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.pypi_package_name }}/blob/main/USAGE.md) or `man {{ cookiecutter.executable_name }}` for details.
+See
+[`USAGE.md`](https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.pypi_package_name }}/blob/main/USAGE.md)
+or `man {{ cookiecutter.executable_name }}` for details.
+
+You can also browse the
+[API reference on Read the Docs](https://{{ cookiecutter.pypi_package_name }}.readthedocs.io/en/stable/autoapi/{{ cookiecutter.python_package_name }}/)
+for details.
 
 ## Contributing to {{ cookiecutter.project_title }}
 
diff --git a/{{ cookiecutter.pypi_package_name }}/contrib/archlinux/{{ cookiecutter.pypi_package_name }}-git/PKGBUILD b/{{ cookiecutter.pypi_package_name }}/contrib/archlinux/{{ cookiecutter.pypi_package_name }}-git/PKGBUILD
@@ -19,6 +19,8 @@ makedepends=(
   'python-myst-parser'
   'python-poetry'
   'python-sphinx'
+  'python-sphinx-autoapi'
+  'python-sphinx_rtd_theme'
   'python-wheel'
 )
 checkdepends=('python-pytest')
diff --git a/{{ cookiecutter.pypi_package_name }}/contrib/archlinux/{{ cookiecutter.pypi_package_name }}-local/PKGBUILD b/{{ cookiecutter.pypi_package_name }}/contrib/archlinux/{{ cookiecutter.pypi_package_name }}-local/PKGBUILD
@@ -18,6 +18,8 @@ makedepends=(
   'python-myst-parser'
   'python-poetry'
   'python-sphinx'
+  'python-sphinx-autoapi'
+  'python-sphinx_rtd_theme'
   'python-wheel'
 )
 checkdepends=('python-pytest')
diff --git a/{{ cookiecutter.pypi_package_name }}/contrib/archlinux/{{ cookiecutter.pypi_package_name }}/PKGBUILD b/{{ cookiecutter.pypi_package_name }}/contrib/archlinux/{{ cookiecutter.pypi_package_name }}/PKGBUILD
@@ -17,6 +17,8 @@ makedepends=(
   'python-myst-parser'
   'python-poetry-core'
   'python-sphinx'
+  'python-sphinx-autoapi'
+  'python-sphinx_rtd_theme'
   'python-wheel'
 )
 checkdepends=('python-pytest')
diff --git a/{{ cookiecutter.pypi_package_name }}/debian/control b/{{ cookiecutter.pypi_package_name }}/debian/control
@@ -16,7 +16,9 @@ Build-Depends: debhelper-compat (= 13),
                python3-all,
                python3-myst-parser,
                python3-poetry-core,
-               python3-sphinx
+               python3-sphinx,
+               python3-sphinx-autoapi,
+               python3-sphinx-rtd-theme
 Standards-Version: 4.5.1
 Homepage: https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.pypi_package_name }}
 Vcs-Browser: https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.pypi_package_name }}
diff --git a/{{ cookiecutter.pypi_package_name }}/doc/sphinx/conf.py b/{{ cookiecutter.pypi_package_name }}/doc/sphinx/conf.py
@@ -6,6 +6,9 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
+# pylint: skip-file
+# type: ignore
+
 project = '{{ cookiecutter.project_title }}'
 executable = '{{ cookiecutter.executable_name }}'
 author = '{{ cookiecutter.author_full_name }} <{{ cookiecutter.author_email }}>'
@@ -15,15 +18,45 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
+    'autoapi.extension',
     'myst_parser',
     'sphinx.ext.autodoc',
-    'sphinx.ext.napoleon',
 ]
 
+autoapi_dirs = ['../../{{ cookiecutter.python_package_name }}']
+autoapi_keep_files = True
+autoapi_options = [
+    'members',
+    'undoc-members',
+    'show-inheritance',
+    'show-module-summary',
+    'special-members',
+    'imported-members',
+]
+autoapi_type = 'python'
+autodoc_typehints = 'description'
+
+html_theme = 'sphinx_rtd_theme'
+
 myst_enable_extensions = [
     'deflist',
 ]
 
+def skip_module(app, what, name, obj, skip, options):
+    if what != 'module':
+        return skip
+    if name in [
+        '{{ cookiecutter.python_package_name }}.version',
+        '{{ cookiecutter.python_package_name }}.settings',
+    ]:
+        return True
+    return skip
+
+
+def setup(sphinx):
+    sphinx.connect('autoapi-skip-member', skip_module)
+
+
 templates_path = []
 exclude_patterns = []
 
diff --git a/{{ cookiecutter.pypi_package_name }}/doc/sphinx/index.rst b/{{ cookiecutter.pypi_package_name }}/doc/sphinx/index.rst
@@ -1,8 +1,12 @@
-Welcome to {{ cookiecutter.project_title }}'s documentation!
+Documentation for {{ cookiecutter.project_title }}
 ====================================
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: Contents
 
    usage
+   autoapi/index
+
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
diff --git a/{{ cookiecutter.pypi_package_name }}/licenses/Apache-2.0-reference.md b/{{ cookiecutter.pypi_package_name }}/licenses/Apache-2.0-reference.md
@@ -2,4 +2,4 @@ Copyright (c) {% now 'local', '%Y' %} {{ cookiecutter.copyright_holder_full_name
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
-For a copy of the License, see [LICENSE](LICENSE).
+For a copy of the License, see [LICENSE](https://raw.githubusercontent.com/{{ cookiecutter.github_username }}/{{ cookiecutter.pypi_package_name }}/refs/heads/main/LICENSE).
diff --git a/{{ cookiecutter.pypi_package_name }}/pyproject.toml b/{{ cookiecutter.pypi_package_name }}/pyproject.toml
@@ -34,6 +34,8 @@ classifiers = [
     "Operating System :: POSIX :: Linux",
     "Topic :: Utilities",
 ]
+documentation = "https://{{ cookiecutter.pypi_package_name }}.readthedocs.io/en/stable/"
+repository = "https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.pypi_package_name }}"
 
 [tool.poetry.dependencies]
 python = ">={{ cookiecutter.python_version }}"
@@ -45,16 +47,19 @@ fire = "*"
 [tool.poetry.group.dev.dependencies]
 autopep8 = "*"
 mypy = ">=1.8"
-myst-parser = ">=2.0.0"
-pdoc = ">=14.0"
 poethepoet = ">=0.24"
 pylint = ">=3.0"
 pytest = "*"
-sphinx = ">=7.1.2,<7.2.0"
 {%- if cookiecutter.include_executable == "y" %}
 types-colorama = "*"
 {%- endif %}
 
+[tool.poetry.group.doc.dependencies]
+myst-parser = ">=2.0.0"
+sphinx = ">=7.1.2,<7.2.0"
+sphinx-autoapi = ">=3.3"
+sphinx-rtd-theme = ">=3.0"
+
 {% if cookiecutter.include_executable == "y" -%}
 [tool.poetry.scripts]
 {{ cookiecutter.executable_name }} = "{{ cookiecutter.python_package_name }}.cli:run"
@@ -71,13 +76,18 @@ tasks.help = "List available tasks"
 cli.script = "{{ cookiecutter.python_package_name }}.cli:run"
 cli.help = "Run command line interface"
 {% endif -%}
-doc.cmd = "sphinx-build -aqEW -b man doc/sphinx build/man"
+doc.shell = """
+    set -ex
+    rm -rf build/html build/man
+    sphinx-build -aqEW -b html doc/sphinx build/html
+    sphinx-build -qW -b man doc/sphinx build/man
+"""
 doc.help = "Generate documentation"
 {% if cookiecutter.include_executable == "y" -%}
 hello.script = "{{ cookiecutter.python_package_name }}.cli:hello"
 hello.help = "Run hello"
 {% endif -%}
-html.cmd = "pdoc {{ cookiecutter.python_package_name }} !{{ cookiecutter.python_package_name }}.settings"
+html.script = "webbrowser:open('build/html/index.html')"
 html.help = "Browse HTML documentation"
 linter.cmd = "pylint --enable-all-extensions {{ cookiecutter.python_package_name }}"
 linter.help = "Check for style violations"
diff --git a/{{ cookiecutter.pypi_package_name }}/{{ cookiecutter.python_package_name }}/__init__.py b/{{ cookiecutter.pypi_package_name }}/{{ cookiecutter.python_package_name }}/__init__.py
@@ -1,7 +1,12 @@
 """
-.. include:: ../README.md
+Usage example:
 
-## API Documentation
+.. code:: python
+
+   from {{ cookiecutter.python_package_name }}.{{ cookiecutter.first_module_name }} import {{ cookiecutter.first_module_name.capitalize() }}
+
+   {{ cookiecutter.first_module_name }} = {{ cookiecutter.first_module_name.capitalize() }}()
+   {{ cookiecutter.first_module_name }}.hello()
 """
 
 # Re-export these symbols
@@ -11,12 +16,7 @@
 from {{ cookiecutter.python_package_name }}.version import version
 
 __all__ = [
-    # Tell pdoc to pick up all re-exported symbols
-    '{{ cookiecutter.first_module_name.capitalize() }}',
-
     # Modules that every subpackage should see
-    # (This also exposes them to pdoc)
-    '{{ cookiecutter.first_module_name }}',
     'settings',
 ]
 
diff --git a/{{ cookiecutter.pypi_package_name }}/{{ cookiecutter.python_package_name }}/logging.py b/{{ cookiecutter.pypi_package_name }}/{{ cookiecutter.python_package_name }}/logging.py
@@ -1,14 +1,16 @@
-"""Customized logging with color support."""
+"""Customized logging{% if cookiecutter.include_executable == "y" %} with color support{% endif %}."""
 
 import logging as python_logging
 
+{% if cookiecutter.include_executable == "y" -%}
 from colorama import Fore, Style
 
+{% endif -%}
 from .settings import debugMode
 
 
 def get_logger(name: str) -> python_logging.Logger:
-    """Instantiate a custom logger with color support."""
+    """Instantiate a custom logger{% if cookiecutter.include_executable == "y" %} with color support{% endif %}."""
     logger = python_logging.getLogger(name)
     logger.setLevel(
         python_logging.DEBUG if debugMode else python_logging.INFO
@@ -23,6 +25,7 @@ class _CustomFormatter(python_logging.Formatter):
     _format = '[%(levelname)s] %(message)s'
 
     FORMATS = {
+        {% if cookiecutter.include_executable == "y" -%}
         python_logging.DEBUG: Style.DIM + _format + Style.RESET_ALL,
         python_logging.INFO: Style.DIM + _format + Style.RESET_ALL,
         python_logging.WARNING: Fore.YELLOW + _format + Style.RESET_ALL,
@@ -31,6 +34,13 @@ class _CustomFormatter(python_logging.Formatter):
         + Fore.RED
         + _format
         + Style.RESET_ALL,
+        {%- else -%}
+        python_logging.DEBUG: _format,
+        python_logging.INFO: _format,
+        python_logging.WARNING: _format,
+        python_logging.ERROR: _format,
+        python_logging.CRITICAL: _format,
+        {%- endif %}
     }
 
     def format(self, record: python_logging.LogRecord) -> str:
