Add unified docs-ci

Related to: pulp/pulp-docs#31

[noissue]

.github/template_gitref

@@ -1 +1 @@
-2021.08.26-326-ge5addc7
+2021.08.26-327-g520b576

.github/workflows/scripts/script.sh

@@ -31,6 +31,8 @@ if [[ "$TEST" = "docs" ]]; then
   if [[ "$GITHUB_WORKFLOW" == "Python CI" ]]; then
     towncrier build --yes --version 4.0.0.ci
   fi
+  # Unified Docs Build
+  pulp-docs build
   # Legacy Docs Build
   cd docs
   make PULP_URL="$PULP_URL" diagrams html
@@ -43,6 +45,12 @@ if [[ "$TEST" = "docs" ]]; then
   exit
 fi
 
+if [[ "$TEST" = "new_docs" ]]; then
+  pip install --user git+https://github.com/pulp/pulp-docs
+  pulp-docs build
+  exit
+fi
+
 REPORTED_STATUS="$(pulp status)"
 
 echo "machine pulp

.github/workflows/test.yml

@@ -23,6 +23,7 @@ jobs:
         env:
           - TEST: pulp
           - TEST: docs
+          - TEST: new_docs
           - TEST: azure
           - TEST: s3
           - TEST: lowerbounds

CHANGES/+new-docs-ci.misc

@@ -0,0 +1 @@
+Added the Unified Docs CI build-check on PRs.

doc_requirements.txt

@@ -1,14 +1,21 @@
-build
-coreapi
-django
-djangorestframework
-django-filter
-drf-nested-routers
-mistune
+# WARNING: DO NOT EDIT!
+#
+# This file was generated by plugin_template, and is managed by it. Please use
+# './plugin-template --docs pulp_python' to update this file.
+#
+# For more info visit https://github.com/pulp/plugin_template
+-r requirements.txt
+towncrier
+
+# Legacy docs
 plantuml
-pyyaml
-sphinx
-sphinx-rtd-theme
+sphinx~=7.1.2
+sphinx-rtd-theme==1.3.0
+sphinxcontrib-jquery
 sphinxcontrib-openapi
-towncrier
-twine
+mistune<4.0.0
+Jinja2<3.2
+
+# Unified docs
+pulp-docs @ git+https://github.com/pulp/pulp-docs@main
+# Extra requirements

docs/Makefile

@@ -1,28 +1,36 @@
+# WARNING: DO NOT EDIT!
+#
+# This file was generated by plugin_template, and is managed by it. Please use
+# './plugin-template --docs pulp_python' to update this file.
+#
+# For more info visit https://github.com/pulp/plugin_template
 # Makefile for Sphinx documentation
 #
 
+SHELL := /bin/bash
 # You can set these variables from the command line.
-SPHINXOPTS = -W -n
+SPHINXOPTS = -W  # turn warnings into errors
 SPHINXBUILD = sphinx-build
 PAPER =
 BUILDDIR = _build
-STATIC_BUILD_DIR = _static
 DIAGRAM_BUILD_DIR = _diagrams
-DIAGRAM_SOURCE_DIR = diagrams_src
-PULP_URL = "http://localhost:24817"
+PULP_URL ?= http://localhost:24817
+PULP_API_ROOT ?= /pulp/
 
 # Internal variables.
+PULP_V3_API_JSON_URL := ${PULP_URL}${PULP_API_ROOT}api/v3/docs/api.json
 PAPEROPT_a4 = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext diagrams
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html       to make standalone HTML files"
+	@echo "  diagrams   to make diagram images"
 	@echo "  dirhtml    to make HTML files named index.html in directories"
 	@echo "  singlehtml to make a single large HTML file"
 	@echo "  pickle     to make pickle files"
@@ -46,26 +54,43 @@ clean:
 	-rm -rf $(BUILDDIR)/*
 	-rm -rf $(DIAGRAM_BUILD_DIR)/*
 
+install:
+	python3 -m venv pulpdocs
+	source pulpdocs/bin/activate && pip install -r ../doc_requirements.txt
+
 diagrams:
-ifneq ($(wildcard $(DIAGRAM_SOURCE_DIR)), )
+ifneq ($(wildcard diagrams_src), )
 	mkdir -p $(DIAGRAM_BUILD_DIR)
-	python3 -m plantuml $(DIAGRAM_SOURCE_DIR)/*.dot
-	# cp + rm = mv  workaround https://pulp.plan.io/issues/4791#note-3
-	cp $(DIAGRAM_SOURCE_DIR)/*.png $(DIAGRAM_BUILD_DIR)/
-	rm $(DIAGRAM_SOURCE_DIR)/*.png
+ifneq ("$(wildcard pulpdocs/bin/activate)","")
+	source pulpdocs/bin/activate && python3 -m plantuml diagrams_src/*.dot
+else
+	python3 -m plantuml diagrams_src/*.dot
+endif
+	mv diagrams_src/*.png $(DIAGRAM_BUILD_DIR)/
 else
 	@echo "Did not find $(DIAGRAM_SOURCE_DIR)."
 endif
 
-html:
-	mkdir -p $(STATIC_BUILD_DIR)
-	curl --fail -o $(STATIC_BUILD_DIR)/api.json "$(PULP_URL)/pulp/api/v3/docs/api.json?component=python&include_html=1"
+$(BUILDDIR)/html/api.json:
+	mkdir -p $(BUILDDIR)/html
+	if pulp debug has-plugin --name core --specifier ">=3.44.0.dev"; \
+	then \
+		curl --fail -o $(BUILDDIR)/html/api.json "$(PULP_V3_API_JSON_URL)?component=python&include_html=1"; \
+	else \
+		curl --fail -o $(BUILDDIR)/html/api.json "$(PULP_V3_API_JSON_URL)?plugin=pulp_python&include_html=1"; \
+	fi
+
+html: $(BUILDDIR)/html/api.json
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ifneq ("$(wildcard pulpdocs/bin/activate)","")
+	source pulpdocs/bin/activate && PULP_CONTENT_ORIGIN=localhost $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+else
+	PULP_CONTENT_ORIGIN=localhost $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+endif
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
@@ -88,7 +113,25 @@ htmlhelp:
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
-		  ".hhp project file in $(BUILDDIR)/htmlhelp."
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PulpDocs.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PulpDocs.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/PulpDocs"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PulpDocs"
+	@echo "# devhelp"
 
 epub:
 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@@ -100,7 +143,7 @@ latex:
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
-		  "(use \`make latexpdf' here to do that automatically)."
+	      "(use \`make latexpdf' here to do that automatically)."
 
 latexpdf:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@@ -123,7 +166,7 @@ texinfo:
 	@echo
 	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
 	@echo "Run \`make' in that directory to run these through makeinfo" \
-		  "(use \`make info' here to do that automatically)."
+	      "(use \`make info' here to do that automatically)."
 
 info:
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@@ -145,9 +188,12 @@ linkcheck:
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
-		  "or in $(BUILDDIR)/linkcheck/output.txt."
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
 
 doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
-		  "results in $(BUILDDIR)/doctest/output.txt."
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+run:
+	cd $(BUILDDIR) && python -m http.server 8010

docs/_templates/restapi.html

@@ -18,7 +18,7 @@
     </style>
   </head>
   <body>
-    <redoc spec-url='_static/api.json'></redoc>
+    <redoc spec-url='api.json'></redoc>
     <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
   </body>
 </html>