antsibull-docs sphinx-init: allow to select other theme (ansible-comm…

…unity#392)

* Make sphinx theme configurable internally.

* Expose command line option to choose Sphinx theme.

* Use other theme in one of the tests.

* Add changelog fragment.

* Use correct markup.

.github/workflows/antsibull-docs.yml

@@ -18,7 +18,7 @@ jobs:
     strategy:
       matrix:
         options:
-          - '--use-current'
+          - '--use-current --sphinx-theme sphinx_rtd_theme'
           - '--use-current --use-html-blobs --no-breadcrumbs community.crypto community.docker'
           # The following should be run without `--use-current` and with `--collection-version 2.0.0`,
           # but that isn't implemented yet:

changelogs/fragments/392-sphinx-init-theme.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - "Allow to select a different Sphinx theme for ``antsibull-docs sphinx-init`` with the new ``--sphinx-theme`` option (https://github.com/ansible-community/antsibull/pull/392)."

src/antsibull/cli/antsibull_docs.py

@@ -328,6 +328,8 @@ def parse_args(program_name: str, args: List[str]) -> argparse.Namespace:
                                     ' one collection specified.')
     sphinx_init_parser.add_argument('--lenient', action='store_true',
                                     help='Configure Sphinx to not be too strict.')
+    sphinx_init_parser.add_argument('--sphinx-theme', default='sphinx-ansible-theme',
+                                    help='Configure the Sphinx theme to use.')
     sphinx_init_parser.add_argument(nargs='*', dest='collections',
                                     help='One or more collections to document.  If the names are'
                                     ' directories on disk, they will be parsed as expanded'

src/antsibull/cli/doc_commands/sphinx_init.py

@@ -64,6 +64,12 @@ def site_init() -> int:
     breadcrumbs = app_ctx.breadcrumbs
     indexes = app_ctx.indexes
 
+    sphinx_theme = 'sphinx_ansible_theme'
+    sphinx_theme_package = 'sphinx-ansible-theme >= 0.9.0'
+    if app_ctx.extra['sphinx_theme'] != 'sphinx-ansible-theme':
+        sphinx_theme = app_ctx.extra['sphinx_theme']
+        sphinx_theme_package = app_ctx.extra['sphinx_theme']
+
     env = doc_environment(('antsibull.data', 'sphinx_init'))
 
     for filename in TEMPLATES:
@@ -80,6 +86,8 @@ def site_init() -> int:
             use_html_blobs=use_html_blobs,
             breadcrumbs=breadcrumbs,
             indexes=indexes,
+            sphinx_theme=sphinx_theme,
+            sphinx_theme_package=sphinx_theme_package,
         ) + '\n'
 
         destination = os.path.join(dest_dir, filename)

src/antsibull/data/sphinx_init/conf_py.j2

@@ -14,7 +14,7 @@ pygments_style = 'ansible'
 
 highlight_language = 'YAML+Jinja'
 
-html_theme = 'sphinx_ansible_theme'
+html_theme = '@{ sphinx_theme }@'
 html_show_sphinx = False
 
 display_version = False

src/antsibull/data/sphinx_init/requirements_txt.j2

@@ -1,4 +1,4 @@
 antsibull >= 0.40.0
 ansible-pygments
 sphinx
-sphinx-ansible-theme >= 0.9.0
+@{ sphinx_theme_package }@