Generate command-line documentation with sphinx-click (#608)

* Add sphinx-click 2.5.0 * Add sphinx-click 2.5.0 to docs/requirements.txt * Configure Sphinx to use sphinx-click * Install sphinx-click in docs and docs-build sessions * Update Usage section in README.rst * Add Usage page to Sphinx documentation * Include Usage page in TOC tree * Do not include Usage section from README.rst * Link to Usage page from README.rst * Document sphinx-click feature in README.rst * Document sphinx-click dependency in User Guide * Document usage.rst file in User Guide Co-Authored-By: Thiago C. D'Ávila <thiagocavila@gmail.com>
cjolowicz · Oct 12, 2020 · 7b405ef · 7b405ef
1 parent 4307969
commit 7b405ef
Show file tree

Hide file tree

Showing 10 changed files with 45 additions and 5 deletions.
diff --git a/README.rst b/README.rst
@@ -84,6 +84,7 @@ Features
 - Security audit with Bandit_ and Safety_
 - Check documentation examples with xdoctest_
 - Generate API documentation with autodoc_ and napoleon_
+- Generate command-line reference with sphinx-click_
 
 The template supports Python 3.6, 3.7, 3.8, and 3.9.
 
@@ -320,6 +321,7 @@ on the *Issues* tab of your GitHub repository,
 .. _pre-commit: https://pre-commit.com/
 .. _pyenv: https://github.com/pyenv/pyenv
 .. _pytest: https://docs.pytest.org/en/latest/
+.. _sphinx-click: https://sphinx-click.readthedocs.io/
 .. _xdoctest: https://github.com/Erotemic/xdoctest
 
 .. references-end
diff --git a/docs/guide.rst b/docs/guide.rst
@@ -596,6 +596,11 @@ The documentation files in the ``docs`` directory are built using Sphinx_:
    It is generated from docstrings and type annotations in the source code,
    using the autodoc_ and napoleon_ extensions.
 
+``usage.rst``
+   The command-line reference for your project.
+   It is generated by inspecting the click_ entry-point in your package,
+   using the sphinx-click_ extension.
+
 The ``docs`` directory contains two more files:
 
 ``conf.py``
@@ -751,6 +756,7 @@ See the table below for an overview of the dependencies of generated projects:
    safety_                 Checks installed dependencies for known vulnerabilities
    sphinx_                 Python documentation generator
    sphinx-autobuild_       Watch a Sphinx directory and rebuild the documentation when a change is detected
+   sphinx-click_           Sphinx extension that automatically documents click applications
    sphinx-rtd-theme_       Read the Docs theme for Sphinx
    typeguard_              Run-time type checker for Python
    xdoctest_               A rewrite of the builtin doctest module

diff --git a/{{cookiecutter.project_name}}/README.rst b/{{cookiecutter.project_name}}/README.rst
@@ -61,7 +61,7 @@ You can install *{{cookiecutter.friendly_name}}* via pip_ from PyPI_:
 Usage
 -----
 
-* TODO
+Please see the `Command-line Reference <Usage_>`_ for details.
 
 
 Contributing
@@ -100,3 +100,4 @@ This project was generated from `@cjolowicz`_'s `Hypermodern Python Cookiecutter
 .. _pip: https://pip.pypa.io/
 .. github-only
 .. _Contributor Guide: CONTRIBUTING.rst
+.. _Usage: https://{{cookiecutter.project_name}}.readthedocs.io/en/latest/usage.html
diff --git a/{{cookiecutter.project_name}}/docs/conf.py b/{{cookiecutter.project_name}}/docs/conf.py
@@ -5,6 +5,11 @@
 project = "{{cookiecutter.friendly_name}}"
 author = "{{cookiecutter.author}}"
 copyright = f"{datetime.now().year}, {author}"
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx_rtd_theme"]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx_click",
+    "sphinx_rtd_theme",
+]
 autodoc_typehints = "description"
 html_theme = "sphinx_rtd_theme"
diff --git a/{{cookiecutter.project_name}}/docs/index.rst b/{{cookiecutter.project_name}}/docs/index.rst
@@ -2,11 +2,13 @@
    :end-before: github-only
 
 .. _Contributor Guide: contributing.html
+.. _Usage: usage.html
 
 .. toctree::
    :hidden:
    :maxdepth: 1
 
+   usage
    reference
    contributing
    Code of Conduct <codeofconduct>

diff --git a/{{cookiecutter.project_name}}/docs/requirements.txt b/{{cookiecutter.project_name}}/docs/requirements.txt
@@ -1,2 +1,3 @@
 sphinx==3.2.1
+sphinx-click==2.5.0
 sphinx-rtd-theme==0.5.0
diff --git a/{{cookiecutter.project_name}}/docs/usage.rst b/{{cookiecutter.project_name}}/docs/usage.rst
@@ -0,0 +1,6 @@
+Usage
+=====
+
+.. click:: {{cookiecutter.package_name}}.__main__:main
+   :prog: {{cookiecutter.project_name}}
+   :nested: full
diff --git a/{{cookiecutter.project_name}}/noxfile.py b/{{cookiecutter.project_name}}/noxfile.py
@@ -163,7 +163,7 @@ def docs_build(session: Session) -> None:
     """Build the documentation."""
     args = session.posargs or ["docs", "docs/_build"]
     session.install(".")
-    session.install("sphinx", "sphinx-rtd-theme")
+    session.install("sphinx", "sphinx-click", "sphinx-rtd-theme")
 
     build_dir = Path("docs", "_build")
     if build_dir.exists():
@@ -177,7 +177,7 @@ def docs(session: Session) -> None:
     """Build and serve the documentation with live reloading on file changes."""
     args = session.posargs or ["--open-browser", "docs", "docs/_build"]
     session.install(".")
-    session.install("sphinx", "sphinx-autobuild", "sphinx-rtd-theme")
+    session.install("sphinx", "sphinx-autobuild", "sphinx-click", "sphinx-rtd-theme")
 
     build_dir = Path("docs", "_build")
     if build_dir.exists():

diff --git a/{{cookiecutter.project_name}}/poetry.lock b/{{cookiecutter.project_name}}/poetry.lock
diff --git a/{{cookiecutter.project_name}}/pyproject.toml b/{{cookiecutter.project_name}}/pyproject.toml
@@ -43,6 +43,7 @@ darglint = "^1.5.5"
 reorder-python-imports = "^2.3.5"
 pre-commit-hooks = "^3.2.0"
 sphinx-rtd-theme = "^0.5.0"
+sphinx-click = "^2.5.0"
 Pygments = "^2.7.1"
 
 [tool.poetry.scripts]