Decouple documentation index from man pages

In general, the HTML documentation can (and should) contain more than
just a single “Usage” chapter. For example, we might want to add a
second man page, and include the latter in the HTML documentation, too.
Or we might want to add unrelated info to the HTML documentation which
is not supposed to show up in a man page.

To accommodate for that, add one layer of indirection so the man page
will be generated from the Usage document, and at the same time, the
Usage document will be included in the HTML documentation.

Author: claui

{{ cookiecutter.pypi_package_name }}/doc/sphinx/conf.py

@@ -7,7 +7,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = '{{ cookiecutter.project_title }}'
-executable_name = '{{ cookiecutter.executable_name }}'
+executable = '{{ cookiecutter.executable_name }}'
 author = '{{ cookiecutter.author_full_name }} <{{ cookiecutter.author_email }}>'
 description = '{{ cookiecutter.project_description }}'
 
@@ -29,18 +29,20 @@
 
 # Man page output
 
-man_pages = [(
-    'index',
-    {% if cookiecutter.include_executable == "y" -%}
-    executable_name,
-    {%- else -%}
-    '{{ cookiecutter.pypi_package_name }}',
-    {%- endif %}
-    description,
-    [author],
-    {% if cookiecutter.include_executable == "y" -%}
-    1,
-    {%- else -%}
-    3,
-    {%- endif %}
-)]
+man_pages = [
+    (
+        'usage',
+        {% if cookiecutter.include_executable == "y" -%}
+        executable,
+        {%- else -%}
+        '{{ cookiecutter.pypi_package_name }}',
+        {%- endif %}
+        description,
+        [author],
+        {% if cookiecutter.include_executable == "y" -%}
+        1,
+        {%- else -%}
+        3,
+        {%- endif %}
+    )
+]

{{ cookiecutter.pypi_package_name }}/doc/sphinx/index.rst

@@ -5,5 +5,4 @@ Welcome to {{ cookiecutter.project_title }}'s documentation!
    :maxdepth: 2
    :caption: Contents:
 
-.. include:: ../../USAGE.md
-   :parser: myst_parser.sphinx_
+   usage

{{ cookiecutter.pypi_package_name }}/doc/sphinx/usage.rst

@@ -0,0 +1,5 @@
+Usage
+=====
+
+.. include:: ../../USAGE.md
+   :parser: myst_parser.sphinx_