From 2bd5450fc4732c3536bbdbfe10b878afcfee9cd5 Mon Sep 17 00:00:00 2001 From: Quirin Pamp Date: Mon, 20 Nov 2023 16:22:37 +0100 Subject: [PATCH 1/3] Have the CI manage the docs [noissue] --- template_config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/template_config.yml b/template_config.yml index e8af34ffe..9eb17e811 100644 --- a/template_config.yml +++ b/template_config.yml @@ -15,7 +15,7 @@ ci_trigger: '{pull_request: {branches: [''*'']}}' ci_update_branches: - '3.0' - '3.1' -ci_update_docs: false +ci_update_docs: true ci_update_release_behavior: null cli_package: pulp-cli-deb cli_repo: https://github.com/pulp/pulp-cli-deb.git From 7857358465fd3695d702458bbd5d7429151cb455 Mon Sep 17 00:00:00 2001 From: Quirin Pamp Date: Mon, 20 Nov 2023 16:26:22 +0100 Subject: [PATCH 2/3] Apply the plugin template [noissue] Ran ./plugin-template --docs pulp_deb Using plugin template commit: bdd41dd6a7e06f792702b6ecd706f44a6a83542d --- doc_requirements.txt | 20 ++++---- docs/Makefile | 78 +++++++++++++++++++++++------- docs/_templates/restapi.html | 2 +- docs/changes.rst | 2 + docs/conf.py | 93 ++++++++++++++++++++++++++++++------ docs/static/.gitkeep | 0 docs/template_gitref | 1 + 7 files changed, 154 insertions(+), 42 deletions(-) mode change 100644 => 100755 docs/conf.py create mode 100644 docs/static/.gitkeep create mode 100644 docs/template_gitref diff --git a/doc_requirements.txt b/doc_requirements.txt index 106dc3434..46e02a753 100644 --- a/doc_requirements.txt +++ b/doc_requirements.txt @@ -1,13 +1,15 @@ -coreapi -django -djangorestframework -django-filter -drf-nested-routers +# WARNING: DO NOT EDIT! +# +# This file was generated by plugin_template, and is managed by it. Please use +# './plugin-template --docs pulp_deb' to update this file. +# +# For more info visit https://github.com/pulp/plugin_template +-r requirements.txt plantuml -pyyaml -sphinx~=6.2.1 -sphinx-rtd-theme==1.2.0 +sphinx~=7.1.2 +sphinx-rtd-theme==1.3.0 sphinxcontrib-jquery sphinxcontrib-openapi towncrier -mistune<2.0.0 +mistune<4.0.0 +Jinja2<3.2 diff --git a/docs/Makefile b/docs/Makefile index 125189f85..6119fa072 100644 --- a/docs/Makefile +++ b/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_deb' 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 ' where 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 - mv $(DIAGRAM_SOURCE_DIR)/*.png $(DIAGRAM_BUILD_DIR)/ +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 -$(STATIC_BUILD_DIR)/api.json: - mkdir -p $(STATIC_BUILD_DIR) - curl --fail -o $(STATIC_BUILD_DIR)/api.json "$(PULP_URL)/pulp/api/v3/docs/api.json?plugin=pulp_deb&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_deb&include_html=1" -html: $(STATIC_BUILD_DIR)/api.json +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 diff --git a/docs/_templates/restapi.html b/docs/_templates/restapi.html index 79601d656..f0933f054 100644 --- a/docs/_templates/restapi.html +++ b/docs/_templates/restapi.html @@ -18,7 +18,7 @@ - + diff --git a/docs/changes.rst b/docs/changes.rst index b7c52b1c2..35c66705d 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -1,3 +1,5 @@ .. _pulp_deb-changes: .. include:: ../CHANGES.rst + +.. include:: ../HISTORY.rst diff --git a/docs/conf.py b/docs/conf.py old mode 100644 new mode 100755 index 4744cdb8b..288f53568 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,8 +1,9 @@ -# -*- coding: utf-8 -*- +# WARNING: DO NOT EDIT! # -# Pulp Python Support documentation build configuration file, created by -# sphinx-quickstart on Thu Nov 20 17:53:15 2014. +# This file was generated by plugin_template, and is managed by it. Please use +# './plugin-template --docs pulp_deb' 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 @@ -13,7 +14,7 @@ import os import sys -sys.path.insert(0, os.path.abspath('..')) # noqa +from datetime import date try: import sphinx_rtd_theme @@ -23,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 ----------------------------------------------------- @@ -32,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', 'sphinxcontrib.jquery'] +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'] @@ -48,7 +65,9 @@ # General information about the project. project = u'Pulp deb 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 @@ -71,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 @@ -93,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 --------------------------------------------------- @@ -106,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 # " v documentation". @@ -127,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. @@ -144,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 @@ -173,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 = { @@ -206,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 @@ -218,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) diff --git a/docs/static/.gitkeep b/docs/static/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/template_gitref b/docs/template_gitref new file mode 100644 index 000000000..b11f949e5 --- /dev/null +++ b/docs/template_gitref @@ -0,0 +1 @@ +2021.08.26-265-gbdd41dd From aa53f0dda99ab001fbfd96de182a51cdb1b8ffb6 Mon Sep 17 00:00:00 2001 From: Quirin Pamp Date: Mon, 20 Nov 2023 16:53:54 +0100 Subject: [PATCH 3/3] Add an empty HISTORY.rst file [noissue] The docs CI automation expects this file to exist. --- HISTORY.rst | 0 MANIFEST.in | 1 + 2 files changed, 1 insertion(+) create mode 100644 HISTORY.rst diff --git a/HISTORY.rst b/HISTORY.rst new file mode 100644 index 000000000..e69de29bb diff --git a/MANIFEST.in b/MANIFEST.in index fbb51bca6..152ac6bc6 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -2,6 +2,7 @@ include CHANGES.rst include COMMITMENT include COPYRIGHT include functest_requirements.txt +include HISTORY.rst include LICENSE include pulp_deb/app/schema/* include pulp_deb/tests/functional/sign_deb_release.sh