Make sphinx-init better configurable (#77)

* Make sphinx-init better configurable.

* Fix template.

* Linting.

* Also support adding values to html_context and html_theme_options.

Author: felixfontein

changelogs/fragments/76-sphinx-init-configurability.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - "Add new options ``--project``, ``--copyright``, ``--title``, ``--html-short-title``, ``--extra-conf``, ``--extra-html-context``, and ``--extra-html-theme-options`` to the ``sphinx-init`` subcommand to allow to customize the generated ``conf.py`` Sphinx configuration (https://github.com/ansible-community/antsibull-docs/pull/77)."

src/antsibull_docs/cli/antsibull_docs.py

@@ -164,6 +164,16 @@ def _normalize_sphinx_init_options(args: argparse.Namespace) -> None:
         raise InvalidArgumentError('The rst/index.rst replacement file,'
                                    f' {args.index_rst_source}, is not a file')
 
+    for key, option in [
+        ('extra_conf', '--extra-conf'),
+        ('extra_html_context', '--extra-html-context'),
+        ('extra_html_theme_options', '--extra-html-theme-options'),
+    ]:
+        for entry in getattr(args, key) or []:
+            if '=' not in entry:
+                raise InvalidArgumentError(
+                    f'Every `{option}` value must have at least one equal sign (=).')
+
 
 def parse_args(program_name: str, args: List[str]) -> argparse.Namespace:
     """
@@ -367,6 +377,31 @@ def parse_args(program_name: str, args: List[str]) -> argparse.Namespace:
     sphinx_init_parser.add_argument('--index-rst-source',
                                     help='Copy the provided file to rst/index.rst intead of'
                                     ' templating a default one.')
+    sphinx_init_parser.add_argument('--project', default='Ansible collections',
+                                    help='Sets the "project" value in the Sphinx configuration.')
+    sphinx_init_parser.add_argument('--copyright', default='Ansible contributors',
+                                    help='Sets the "copyright" value in the Sphinx configuration.')
+    sphinx_init_parser.add_argument('--title', default='Ansible Collections Documentation',
+                                    help='Sets the "title" and "html_short_title" values in the'
+                                    ' Sphinx configuration. If --html-short-title is also'
+                                    ' specified, only "title" will be set to the value specified'
+                                    ' here.')
+    sphinx_init_parser.add_argument('--html-short-title',
+                                    help='Sets the "html_short_title" value in the Sphinx'
+                                    ' configuration. If not specified, the value of --title will'
+                                    ' be used.')
+    sphinx_init_parser.add_argument('--extra-conf', action='append',
+                                    help='Add additional configuration entries to the generated'
+                                    ' conf.py. Use the syntax `key=value` to add an entry'
+                                    ' `key = "value"`.')
+    sphinx_init_parser.add_argument('--extra-html-context', action='append',
+                                    help='Add additional configuration entries to the generated'
+                                    ' conf.py in `html_context`. Use the syntax `key=value` to add'
+                                    ' an entry `"key": "value",`.')
+    sphinx_init_parser.add_argument('--extra-html-theme-options', action='append',
+                                    help='Add additional configuration entries to the generated'
+                                    ' conf.py in `html_theme_options`. Use the syntax `key=value`'
+                                    ' to add an entry `"key": "value",`.')
 
     #
     # Lint collection docs

src/antsibull_docs/cli/doc_commands/sphinx_init.py

@@ -78,6 +78,14 @@ def python_repr(value: t.Any) -> str:
     return repr(value)
 
 
+def split_kv(entries: t.Optional[t.List[str]]) -> t.List[t.Tuple[str, str]]:
+    result: t.List[t.Tuple[str, str]] = []
+    for entry in entries or []:
+        key, value = entry.split('=', 1)
+        result.append((key, value))
+    return result
+
+
 def site_init() -> int:
     """
     Initialize a Sphinx site template for a collection docsite.
@@ -109,7 +117,16 @@ def site_init() -> int:
     for intersphinx in app_ctx.extra['intersphinx'] or []:
         inventory, url = intersphinx.split(':', 1)
         intersphinx_parts.append((inventory.rstrip(' '), url.lstrip(' ')))
-    index_rst_source = app_ctx.extra['index_rst_source']
+    index_rst_source: t.Optional[str] = app_ctx.extra['index_rst_source']
+    project: str = app_ctx.extra['project']
+    conf_copyright: str = app_ctx.extra['copyright']
+    title: str = app_ctx.extra['title']
+    html_short_title: t.Optional[str] = app_ctx.extra['html_short_title']
+    if html_short_title is None:
+        html_short_title = title
+    extra_conf = split_kv(app_ctx.extra['extra_conf'])
+    extra_html_context = split_kv(app_ctx.extra['extra_html_context'])
+    extra_html_theme_options = split_kv(app_ctx.extra['extra_html_theme_options'])
 
     sphinx_theme = 'sphinx_ansible_theme'
     sphinx_theme_package = 'sphinx-ansible-theme >= 0.9.0'
@@ -148,6 +165,13 @@ def site_init() -> int:
             collection_url=collection_url,
             collection_install=collection_install,
             intersphinx=intersphinx_parts,
+            project=project,
+            conf_copyright=conf_copyright,
+            title=title,
+            html_short_title=html_short_title,
+            extra_conf=extra_conf,
+            extra_html_context=extra_html_context,
+            extra_html_theme_options=extra_html_theme_options,
         ) + '\n'
 
         destination = os.path.join(dest_dir, filename)

src/antsibull_docs/data/sphinx_init/conf_py.j2

@@ -6,19 +6,19 @@
 # documentation:
 # http://www.sphinx-doc.org/en/master/config
 
-project = 'Ansible collections'
-copyright = 'Ansible contributors'
+project = @{ project | python_repr }@
+copyright = @{ conf_copyright | python_repr }@
 
-title = 'Ansible Collections Documentation'
-html_short_title = 'Ansible Collections Documentation'
+title = @{ title | python_repr }@
+html_short_title = @{ html_short_title | python_repr }@
 
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx_antsibull_ext']
 
 pygments_style = 'ansible'
 
 highlight_language = 'YAML+Jinja'
 
-html_theme = '@{ sphinx_theme }@'
+html_theme = @{ sphinx_theme | python_repr }@
 html_show_sphinx = False
 
 display_version = False
@@ -49,3 +49,25 @@ default_role = 'any'
 {% if not lenient %}
 nitpicky = True
 {% endif %}
+{% if extra_conf %}
+
+{%   for key, value in extra_conf %}
+@{ key }@ = @{ value | python_repr }@
+{%   endfor %}
+{% endif %}
+{% if extra_html_context %}
+
+html_context = {
+{%   for key, value in extra_conf %}
+    @{ key | python_repr }@: @{ value | python_repr }@,
+{%   endfor %}
+}
+{% endif %}
+{% if extra_html_theme_options %}
+
+html_theme_options = {
+{%   for key, value in extra_conf %}
+    @{ key | python_repr }@: @{ value | python_repr }@,
+{%   endfor %}
+}
+{% endif %}