Add --intersphinx option to sphinx-init subcommand (#44)

* Add --intersphinx option to sphinx-init subcommand.

* Linting.

.github/workflows/antsibull-docs.yml

@@ -25,7 +25,7 @@ jobs:
         options:
           - '--use-current --sphinx-theme sphinx_rtd_theme'
           - '--use-current --use-html-blobs --no-breadcrumbs community.crypto community.docker'
-          - '--no-indexes --squash-hierarchy community.crypto --collection-version 2.0.0'
+          - '--no-indexes --squash-hierarchy --intersphinx ansible6:https://docs.ansible.com/ansible/6/ community.crypto --collection-version 2.0.0'
 
     steps:
       - name: Check out antsibull-docs

changelogs/fragments/44-intersphinx.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - "Add ``--intersphinx`` option to the ``sphinx-init`` subcommand to allow adding additional ``intersphinx_mapping`` entries to ``conf.py`` (https://github.com/ansible-community/antsibull-docs/issues/35, https://github.com/ansible-community/antsibull-docs/pull/44)."

src/antsibull_docs/cli/antsibull_docs.py

@@ -155,6 +155,11 @@ def _normalize_sphinx_init_options(args: argparse.Namespace) -> None:
         raise InvalidArgumentError('If no collection is provided, --use-current must be'
                                    ' specified')
 
+    for intersphinx in args.intersphinx or []:
+        if ':' not in intersphinx:
+            raise InvalidArgumentError(
+                'Every `--intersphinx` value must have at least one colon (:).')
+
 
 def parse_args(program_name: str, args: List[str]) -> argparse.Namespace:
     """
@@ -350,6 +355,11 @@ def parse_args(program_name: str, args: List[str]) -> argparse.Namespace:
                                     ' names, they will be downloaded from galaxy.  If no names are'
                                     ' provided, --use-current must be supplied and docs are built'
                                     ' for all collections found.')
+    sphinx_init_parser.add_argument('--intersphinx', action='append',
+                                    help='Add entries to intersphinx_mapping in the generated'
+                                    ' conf.py. Use the syntax `identifier:https://server/path` to'
+                                    ' add the identifier `identifier` with URL'
+                                    ' `https://server/path`. The inventory is always `None`.')
 
     #
     # Lint collection docs

src/antsibull_docs/cli/doc_commands/sphinx_init.py

@@ -56,6 +56,10 @@ def toperky(value: t.Any) -> str:
     raise Exception(f'toperky filter cannot handle type {type(value)}')
 
 
+def python_repr(value: t.Any) -> str:
+    return repr(value)
+
+
 def site_init() -> int:
     """
     Initialize a Sphinx site template for a collection docsite.
@@ -83,6 +87,10 @@ def site_init() -> int:
     indexes = app_ctx.indexes
     collection_url = app_ctx.collection_url
     collection_install = app_ctx.collection_install
+    intersphinx_parts = []
+    for intersphinx in app_ctx.extra['intersphinx'] or []:
+        inventory, url = intersphinx.split(':', 1)
+        intersphinx_parts.append((inventory.rstrip(' '), url.lstrip(' ')))
 
     sphinx_theme = 'sphinx_ansible_theme'
     sphinx_theme_package = 'sphinx-ansible-theme >= 0.9.0'
@@ -92,7 +100,10 @@ def site_init() -> int:
 
     env = doc_environment(
         ('antsibull_docs.data', 'sphinx_init'),
-        extra_filters={'toperky': toperky},
+        extra_filters={
+            'toperky': toperky,
+            'python_repr': python_repr,
+        },
     )
 
     for filename in TEMPLATES:
@@ -114,6 +125,7 @@ def site_init() -> int:
             sphinx_theme_package=sphinx_theme_package,
             collection_url=collection_url,
             collection_install=collection_install,
+            intersphinx=intersphinx_parts,
         ) + '\n'
 
         destination = os.path.join(dest_dir, filename)

src/antsibull_docs/data/sphinx_init/conf_py.j2

@@ -28,11 +28,18 @@ html_use_modindex = False
 html_use_index = False
 html_copy_source = False
 
+# See https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_mapping for the syntax
 intersphinx_mapping = {
     'python': ('https://docs.python.org/2/', (None, '../python2.inv')),
     'python3': ('https://docs.python.org/3/', (None, '../python3.inv')),
     'jinja2': ('http://jinja.palletsprojects.com/', (None, '../jinja2.inv')),
     'ansible_devel': ('https://docs.ansible.com/ansible/devel/', (None, '../ansible_devel.inv')),
+{% if intersphinx %}
+    # The following @{ 'entry was' if intersphinx | length == 1 else 'entries were' }@ passed to `antsibull-docs sphinx-init`:
+{%   for inventory, url in intersphinx %}
+    @{ inventory | python_repr }@: (@{ url | python_repr }@, None),
+{%   endfor %}
+{% endif %}
     # If you want references to resolve to a released Ansible version (say, `5`), uncomment and replace X by this version:
     # 'ansibleX': ('https://docs.ansible.com/ansible/X/', (None, '../ansibleX.inv')),
 }