Update docs template

.github/workflows/scripts/post_before_install.sh

@@ -0,0 +1,4 @@
+if [[ "$TEST" = "docs" || "$TEST" = "publish" ]]
+then
+  sudo apt-get install -y libgirepository1.0-dev
+fi

doc_requirements.txt

@@ -1,4 +1,15 @@
+# WARNING: DO NOT EDIT!
+#
+# This file was generated by plugin_template, and is managed by it. Please use
+# './plugin-template --docs pulp_ostree' to update this file.
+#
+# For more info visit https://github.com/pulp/plugin_template
+-r requirements.txt
 plantuml
-sphinx
-sphinx-rtd-theme
+sphinx~=7.1.2
+sphinx-rtd-theme==1.3.0
+sphinxcontrib-jquery
+sphinxcontrib-openapi
 towncrier
+mistune<4.0.0
+Jinja2<3.2

docs/Makefile

@@ -1,28 +1,37 @@
+# WARNING: DO NOT EDIT!
+#
+# This file was generated by plugin_template, and is managed by it. Please use
+# './plugin-template --docs pulp_ostree' 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 +55,38 @@ 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?plugin=pulp_ostree&include_html=1"
+$(BUILDDIR)/html/api.json:
+	mkdir -p $(BUILDDIR)/html
+	curl --fail -o $(BUILDDIR)/html/api.json "$(PULP_V3_API_JSON_URL)?plugin=pulp_ostree&include_html=1"
+
+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 +109,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 +139,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 +162,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 +184,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>

docs/conf.py

@@ -1,6 +1,9 @@
-# Pulp Python Support documentation build configuration file, created by
-# sphinx-quickstart on Thu Nov 20 17:53:15 2014.
+# WARNING: DO NOT EDIT!
 #
+# This file was generated by plugin_template, and is managed by it. Please use
+# './plugin-template --docs pulp_ostree' to update this file.
+#
+# For more info visit https://github.com/pulp/plugin_template
 # This file is execfile()d with the current directory set to its containing dir.
 #
 # Note that not all possible configuration values are present in this
@@ -11,7 +14,7 @@
 
 import os
 import sys
-sys.path.insert(0, os.path.abspath('..'))  # noqa
+from datetime import date
 
 try:
     import sphinx_rtd_theme
@@ -21,7 +24,16 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('./extensions'))  # noqa
+
+sys.path.insert(0, os.path.abspath('..'))  # noqa
+
+
+# Set environment variable so Sphinx can bootstrap the Django app
+os.environ["DJANGO_SETTINGS_MODULE"] = "pulpcore.app.settings"
+
+import django
+django.setup()
 
 # -- General configuration -----------------------------------------------------
 
@@ -30,7 +42,14 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.extlinks']
+extensions = [
+    'sphinx.ext.extlinks',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.napoleon',
+    'sphinxcontrib.openapi',
+    'sphinxcontrib.jquery',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -46,7 +65,9 @@
 
 # General information about the project.
 project = u'Pulp ostree Support'
-copyright = u''
+
+# Set copyright to current year
+copyright = u'2012-{0}, Pulp Team'.format(date.today().year)
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -69,7 +90,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-patterns = ['_build']
+exclude_patterns = ['_build', 'pulpdocs']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
@@ -91,6 +112,12 @@
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
+# Set autodoc default options
+# Document all module/class/etc members, even if they have no docstring.
+# Show class inheritance, and group class members together by type (attr, method, etc)
+autodoc_default_flags = ['members', 'undoc-members']
+autodoc_member_order = 'groupwise'
+autoclass_content = 'both'
 
 # -- Options for HTML output ---------------------------------------------------
 
@@ -104,7 +131,7 @@
 #html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] if sphinx_rtd_theme else []
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -125,7 +152,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] if sphinx_rtd_theme else []
+html_static_path = ['static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -142,9 +169,6 @@
 # template names.
 html_additional_pages = {'restapi': 'restapi.html'}
 
-html_static_path = ['_static']
-
-
 # If false, no module index is generated.
 #html_domain_indices = True
 
@@ -171,6 +195,10 @@
 # This is the file name suffix for HTML files (e.g. ".xhtml").
 #html_file_suffix = None
 
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'PulpDocs'
+
+
 # -- Options for LaTeX output --------------------------------------------------
 
 latex_elements = {
@@ -204,7 +232,6 @@
 # If false, no module index is generated.
 #latex_domain_indices = True
 
-
 # If true, show URL addresses after external links.
 #man_show_urls = False
 
@@ -216,3 +243,43 @@
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
+
+extlinks = {
+    'github': ('https://github.com/pulp/pulpcore/issues/%s', '#%s'),
+    'redmine': ('https://pulp.plan.io/issues/%s', '#%s'),
+}
+
+# napoleon uses .. attribute by default, but :ivar: is more succinct and looks better,
+# particularly on classes with a lot of attributes, like django models and related objects
+napoleon_use_ivar = True
+
+# set primary domain to python so we don't have to include :py: in xref links
+default_domain = 'py'
+
+from sphinx.domains.python import PythonDomain
+
+# Adapted from:
+# https://github.com/sphinx-doc/sphinx/issues/3866#issuecomment-366014346
+# Required because pulpcore.app and pulpcore.plugin have the same class names
+# and Sphinx can't figure out which it should be using. This code defaults to
+# pulpcore.app
+class MyPythonDomain(PythonDomain):
+    def find_obj(self, env, modname, classname, name, type, searchmode=0):
+        """Ensures an object always resolves to the desired module if defined there."""
+        orig_matches = PythonDomain.find_obj(self, env, modname, classname, name, type, searchmode)
+        matches = []
+        for match in orig_matches:
+            match_name = match[0]
+            desired_name = "pulpcore.app.models." + name.strip('.')
+            if match_name == desired_name:
+                matches.append(match)
+                break
+        if matches:
+            return matches
+        else:
+            return orig_matches
+
+
+def setup(sphinx):
+    """Use MyPythonDomain in place of PythonDomain"""
+    sphinx.add_domain(MyPythonDomain, override=True)

docs/template_gitref

@@ -1 +1 @@
-2021.04.08-75-gc58df11
+2021.08.26-244-g7bb934c

template_config.yml

@@ -1,7 +1,7 @@
 # This config represents the latest values used when running the plugin-template. Any settings that
 # were not present before running plugin-template have been added with their default values.
 
-# generated with plugin_template@2021.08.26-241-g9cfc63e
+# generated with plugin_template@2021.08.26-244-g7bb934c
 
 additional_repos: []
 api_root: /pulp/
@@ -13,7 +13,7 @@ check_stray_pulpcore_imports: true
 ci_env: {}
 ci_trigger: '{pull_request: {branches: [''*'']}}'
 ci_update_branches: []
-ci_update_docs: false
+ci_update_docs: true
 ci_update_release_behavior: null
 cli_package: pulp-cli-ostree
 cli_repo: https://github.com/pulp/pulp-cli-ostree.git