Add new docs CI build test activated by flags

* Adds basic testing for the new docs build, which uses pulp-docs to
aggregate all docs.
* Use flags for switching legacy and/or unified CIs

Co-authored-by: Matthias Dellweg <2500@gmx.de>
[noissue]

CHANGES/+add-new-docs-test.feature

@@ -0,0 +1 @@
+Added basic testing to the new docs to check it can build.

README.md

@@ -200,6 +200,8 @@ The following settings are stored in `template_config.yml`.
   pre_job_template      holds name and a path for a template to be included to run before jobs.
   post_job_template     holds name and a path for a template to be included to run after jobs.
   lint_requirements     Boolean (defaults True) to enable upper bound check on requirements.txt
+  use_unified_docs      Boolean (defaults False) to enable the unified docs CI (see [pulp-docs](https://github.com/pulp/pulp-docs).
+  use_legacy_docs       Boolean (defaults True) to enable the legacy docs CI.
 ```
 
 # Bootstrap a new Pulp plugin

plugin-template

@@ -82,6 +82,8 @@ DEFAULT_SETTINGS = {
     "test_reroute": True,
     "test_s3": False,
     "use_issue_template": True,
+    "use_legacy_docs": True,
+    "use_unified_docs": False,
 }
 
 

templates/docs/doc_requirements.txt.j2

@@ -1,13 +1,23 @@
 {% include 'header.j2' %}
 -r requirements.txt
+towncrier
+{%- if use_legacy_docs %}
+
+# Legacy docs
 plantuml
 sphinx~=7.1.2
 sphinx-rtd-theme==1.3.0
 sphinxcontrib-jquery
 sphinxcontrib-openapi
-towncrier
 mistune<4.0.0
 Jinja2<3.2
+{%- endif %}
+{%- if use_unified_docs %}
+
+# Unified docs
+pulp-docs @ git+https://github.com/pulp/pulp-docs@main
+{%- endif %}
+# Extra requirements
 {%- for req in extra_docs_requirements %}
 {{ req }}
 {%- endfor %}

templates/github/.github/workflows/scripts/script.sh.j2

@@ -26,6 +26,12 @@ if [[ "$TEST" = "docs" ]]; then
   if [[ "$GITHUB_WORKFLOW" == "{{ plugin_app_label | camel | default("Pulp") }} CI" ]]; then
     towncrier build --yes --version 4.0.0.ci
   fi
+{%- if use_unified_docs %}
+  # Unified Docs Build
+  pulp-docs build
+{%- endif %}
+{%- if use_legacy_docs %}
+  # Legacy Docs Build
   cd docs
   make PULP_URL="$PULP_URL" diagrams html
   tar -cvf docs.tar ./_build
@@ -34,6 +40,7 @@ if [[ "$TEST" = "docs" ]]; then
   if [ -f "$POST_DOCS_TEST" ]; then
     source "$POST_DOCS_TEST"
   fi
+{%- endif %}
   exit
 fi