Merge pull request #16 from adamtheturtle/full-docs

Add Sphinx documentation with ReadTheDocs

.github/workflows/release.yml

@@ -144,7 +144,7 @@ jobs:
         with:
           destination_branch: master
           source_file: ${{ steps.homebrew-create.outputs.HOMEBREW_RECIPE_FILE }}
-          destination_repo: 'VWS-Python/homebrew-vws'
+          destination_repo: 'adamtheturtle/homebrew-doccmd'
           user_email: '[email protected]'
           user_name: 'adamtheturtle'
           commit_message: 'Bump CLI Homebrew recipe'

.pre-commit-config.yaml

@@ -6,25 +6,31 @@ ci:
     # We therefore cannot use those dependencies in pre-commit CI.
     skip:
         - actionlint
-        - mypy
         - check-manifest
-        - pyright
-        - vulture
-        - pyroma
         - deptry
-        - pylint
-        - ruff-check
-        - ruff-format-diff
-        - ruff-check-fix
-        - ruff-format-fix
         - doc8
+        - docs
         - interrogate
+        - interrogate-docs
+        - linkcheck
+        - mypy
+        - mypy-docs
+        - pylint
         - pyproject-fmt-check
         - pyproject-fmt-fix
-        - linkcheck
+        - pyright
+        - pyright-docs
+        - pyroma
+        - ruff-check
+        - ruff-check-docs
+        - ruff-check-fix
+        - ruff-check-fix-docs
+        - ruff-format-diff
+        - ruff-format-diff-docs
+        - ruff-format-fix
+        - ruff-format-fix-docs
         - spelling
-        - docs
-        - pyright-verifytypes
+        - vulture
 
 default_install_hook_types: [pre-commit, pre-push, commit-msg]
 repos:
@@ -208,3 +214,26 @@ repos:
         language: system
         types_or: [toml]
         files: pyproject.toml
+
+    -   id: linkcheck
+        name: linkcheck
+        entry: make -C docs/ linkcheck SPHINXOPTS=-W
+        language: system
+        types_or: [rst]
+        stages: [manual]
+        pass_filenames: false
+
+    -   id: spelling
+        name: spelling
+        entry: make -C docs/ spelling SPHINXOPTS=-W
+        language: system
+        types_or: [rst]
+        stages: [manual]
+        pass_filenames: false
+
+    -   id: docs
+        name: Build Documentation
+        entry: make docs
+        language: system
+        stages: [manual]
+        pass_filenames: false

CHANGELOG.rst

@@ -0,0 +1,5 @@
+Changelog
+=========
+
+Next
+----

Makefile

@@ -0,0 +1,12 @@
+SHELL := /bin/bash -euxo pipefail
+
+# Treat Sphinx warnings as errors
+SPHINXOPTS := -W
+
+.PHONY: docs
+docs:
+	make -C docs clean html SPHINXOPTS=$(SPHINXOPTS)
+
+.PHONY: open-docs
+open-docs:
+	python -c 'import os, webbrowser; webbrowser.open("file://" + os.path.abspath("docs/build/html/index.html"))'

README.rst

@@ -75,13 +75,17 @@ What does it work on?
 
 TODO:
 
-* Add documentation (automated, and link to it, and add pre-commits for Sphinx stuff, update urls.Source)
 * Release pre-commit hook
 * Verbose mode... "Running command "X" against README.rst example from line ..."
 * Option to not delete file
 * Document https://sybil.readthedocs.io/en/latest/rest.html#skipping-examples on docrun, and make it work
 * https://github.com/simplistix/sybil/blob/master/sybil/parsers/rest/codeblock.py add .. code (not just code block), and same for MyST where it is even more popular
 
+Full documentation
+------------------
+
+See the `full documentation <https://doccmd.readthedocs.io/en/latest>`__.
+
 .. |Build Status| image:: https://github.com/adamtheturtle/doccmd/actions/workflows/ci.yml/badge.svg?branch=main
    :target: https://github.com/adamtheturtle/doccmd/actions
 .. |codecov| image:: https://codecov.io/gh/adamtheturtle/doccmd/branch/main/graph/badge.svg

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/__init__.py

@@ -0,0 +1 @@
+"""Documentation for `doccmd`."""

docs/source/changelog.rst

@@ -0,0 +1 @@
+.. include:: ../../CHANGELOG.rst

docs/source/commands.rst

@@ -0,0 +1,6 @@
+Commands
+========
+
+.. click:: doccmd:main
+  :prog: doccmd
+  :show-nested:

docs/source/conf.py

@@ -0,0 +1,80 @@
+"""Configuration for Sphinx."""
+
+# pylint: disable=invalid-name
+
+import datetime
+import importlib.metadata
+
+project = "doccmd"
+author = "Adam Dangoor"
+
+extensions = [
+    "sphinx_copybutton",
+    "sphinxcontrib.spelling",
+    "sphinx_click.ext",
+    "sphinx_inline_tabs",
+    "sphinx_substitution_extensions",
+]
+
+templates_path = ["_templates"]
+source_suffix = ".rst"
+master_doc = "index"
+
+year = datetime.datetime.now(tz=datetime.UTC).year
+project_copyright = f"{year}, {author}"
+
+# Exclude the prompt from copied code with sphinx_copybutton.
+# https://sphinx-copybutton.readthedocs.io/en/latest/use.html#automatic-exclusion-of-prompts-from-the-copies.
+copybutton_exclude = ".linenos, .gp"
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# Use ``importlib.metadata.version`` as per
+# https://setuptools-scm.readthedocs.io/en/latest/usage/#usage-from-sphinx.
+version = importlib.metadata.version(distribution_name=project)
+_month, _day, _year, *_ = version.split(".")
+release = f"{_month}.{_day}.{_year}"
+
+language = "en"
+
+# The name of the syntax highlighting style to use.
+pygments_style = "sphinx"
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "doccmd"
+autoclass_content = "init"
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3.12", None),
+}
+nitpicky = True
+warning_is_error = True
+
+html_show_copyright = False
+html_show_sphinx = False
+html_show_sourcelink = False
+autoclass_content = "both"
+
+html_theme = "furo"
+html_title = project
+html_show_copyright = False
+html_show_sphinx = False
+html_show_sourcelink = False
+html_theme_options = {
+    "sidebar_hide_name": False,
+}
+
+# Retry link checking to avoid transient network errors.
+linkcheck_retries = 5
+
+spelling_word_list_filename = "../../spelling_private_dict.txt"
+
+autodoc_member_order = "bysource"
+
+rst_prolog = f"""
+.. |project| replace:: {project}
+.. |release| replace:: {release}
+.. |github-owner| replace:: adamtheturtle
+.. |github-repository| replace:: doccmd
+"""

docs/source/contributing.rst

@@ -0,0 +1,79 @@
+Contributing to |project|
+=========================
+
+Contributions to this repository must pass tests and linting.
+
+CI is the canonical source of truth.
+
+Install contribution dependencies
+---------------------------------
+
+Install Python dependencies in a virtual environment.
+
+.. code-block:: console
+
+   $ pip install --editable '.[dev]'
+
+Spell checking requires ``enchant``.
+This can be installed on macOS, for example, with `Homebrew`_:
+
+.. code-block:: console
+
+   $ brew install enchant
+
+and on Ubuntu with ``apt``:
+
+.. code-block:: console
+
+   $ apt-get install -y enchant
+
+Install ``pre-commit`` hooks:
+
+.. code-block:: console
+
+   $ pre-commit install
+
+Linting
+-------
+
+Run lint tools either by committing, or with:
+
+.. code-block:: console
+
+   $ pre-commit run --all-files --hook-stage commit --verbose
+   $ pre-commit run --all-files --hook-stage push --verbose
+   $ pre-commit run --all-files --hook-stage manual --verbose
+
+.. _Homebrew: https://brew.sh
+
+Running tests
+-------------
+
+Run ``pytest``:
+
+.. code-block:: console
+
+   $ pytest
+
+Documentation
+-------------
+
+Documentation is built on Read the Docs.
+
+Run the following commands to build and view documentation locally:
+
+.. code-block:: console
+
+   $ make docs
+   $ make open-docs
+
+Continuous integration
+----------------------
+
+Tests are run on GitHub Actions.
+The configuration for this is in :file:`.github/workflows/`.
+
+Performing a release
+--------------------
+
+See :doc:`release-process`.

docs/source/index.rst

@@ -0,0 +1,50 @@
+|project|
+=========
+
+A command line tool for running commands against documentation files.
+
+.. include:: install.rst
+
+.. include:: usage-example.rst
+
+What does it work on?
+---------------------
+
+* reStructuredText (`.rst`)
+
+.. code-block:: rst
+
+   .. code-block:: shell
+
+      echo "Hello, world!"
+
+* Markdown (`.md`)
+
+.. code-block:: markdown
+
+   ```shell
+   echo "Hello, world!"
+   ```
+
+* MyST (`.md` with MyST syntax)
+
+.. code-block:: markdown
+
+   ```{code-block} shell
+   echo "Hello, world!"
+   ```
+
+* Want more? Open an issue!
+
+Reference
+---------
+
+.. toctree::
+   :maxdepth: 3
+
+   install
+   usage-example
+   commands
+   contributing
+   release-process
+   changelog

docs/source/install.rst

@@ -0,0 +1,32 @@
+Installation
+------------
+
+With ``pip``
+~~~~~~~~~~~~
+
+Requires Python 3.12+.
+
+.. code-block:: shell
+
+   pip install doccmd
+
+With Homebrew (macOS, Linux, WSL)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Requires `Homebrew`_.
+
+.. code-block:: shell
+
+   brew tap adamtheturtle/doccmd
+   brew install doccmd
+
+.. _Homebrew: https://docs.brew.sh/Installation
+
+Pre-built Linux binaries
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: console
+   :substitutions:
+
+   $ curl --fail -L https://github.com/|github-owner|/|github-repository|/releases/download/|release|/doccmd -o /usr/local/bin/doccmd && \
+   $ chmod +x /usr/local/bin/doccmd