From 8afd6c140d38b9ffcea895d6c13bc11026577986 Mon Sep 17 00:00:00 2001 From: Pedro Brochado Date: Mon, 15 Apr 2024 18:22:11 -0300 Subject: [PATCH] Add unified docs-ci Related to: https://github.com/pulp/pulp-docs/issues/31 [noissue] --- .github/template_gitref | 2 +- .github/workflows/scripts/script.sh | 8 +++ .github/workflows/test.yml | 1 + CHANGES/+new-docs-ci.misc | 1 + doc_requirements.txt | 31 +++++---- docs/Makefile | 84 +++++++++++++++++++------ docs/_templates/restapi.html | 2 +- docs/conf.py | 98 +++++++++++++++++++++++------ docs/static/.gitkeep | 0 docs/template_gitref | 1 + template_config.yml | 2 +- 11 files changed, 178 insertions(+), 52 deletions(-) create mode 100644 CHANGES/+new-docs-ci.misc mode change 100644 => 100755 docs/conf.py create mode 100644 docs/static/.gitkeep create mode 100644 docs/template_gitref diff --git a/.github/template_gitref b/.github/template_gitref index 9ec4e6fe..e169228c 100644 --- a/.github/template_gitref +++ b/.github/template_gitref @@ -1 +1 @@ -2021.08.26-326-ge5addc7 +2021.08.26-327-g520b576 diff --git a/.github/workflows/scripts/script.sh b/.github/workflows/scripts/script.sh index 131ad0dc..9c7caa6f 100755 --- a/.github/workflows/scripts/script.sh +++ b/.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 diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index e5b52a60..2f8e224d 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -23,6 +23,7 @@ jobs: env: - TEST: pulp - TEST: docs + - TEST: new_docs - TEST: azure - TEST: s3 - TEST: lowerbounds diff --git a/CHANGES/+new-docs-ci.misc b/CHANGES/+new-docs-ci.misc new file mode 100644 index 00000000..91a15718 --- /dev/null +++ b/CHANGES/+new-docs-ci.misc @@ -0,0 +1 @@ +Added the Unified Docs CI build-check on PRs. diff --git a/doc_requirements.txt b/doc_requirements.txt index 925c79a0..205ad578 100644 --- a/doc_requirements.txt +++ b/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 diff --git a/docs/Makefile b/docs/Makefile index 1716b258..4f8d095c 100644 --- a/docs/Makefile +++ b/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 ' 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 +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 diff --git a/docs/_templates/restapi.html b/docs/_templates/restapi.html index 89dcb1a0..e0714b8c 100644 --- a/docs/_templates/restapi.html +++ b/docs/_templates/restapi.html @@ -18,7 +18,7 @@ - + diff --git a/docs/conf.py b/docs/conf.py old mode 100644 new mode 100755 index 656e41a8..fed1865a --- 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_python' 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,8 +14,7 @@ import os import sys -sys.path.insert(0, os.path.abspath('..')) # noqa - +from datetime import date try: import sphinx_rtd_theme @@ -24,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 ----------------------------------------------------- @@ -33,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'] @@ -44,12 +60,14 @@ # The encoding of source files. #source_encoding = 'utf-8-sig' -# The master toctree document. +# The top level toctree document. master_doc = 'index' # General information about the project. project = u'Pulp python 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 @@ -72,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 @@ -94,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 --------------------------------------------------- @@ -107,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". @@ -128,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. @@ -145,11 +169,6 @@ # template names. html_additional_pages = {'restapi': 'restapi.html'} -html_static_path = ['_static'] - -# Re-enable this when new survey is created. -# html_js_files = ['survey_banner.js'] - # If false, no module index is generated. #html_domain_indices = True @@ -176,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 = { @@ -209,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 @@ -221,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 00000000..e69de29b diff --git a/docs/template_gitref b/docs/template_gitref new file mode 100644 index 00000000..e169228c --- /dev/null +++ b/docs/template_gitref @@ -0,0 +1 @@ +2021.08.26-327-g520b576 diff --git a/template_config.yml b/template_config.yml index 09374374..ee3c52ea 100644 --- a/template_config.yml +++ b/template_config.yml @@ -74,5 +74,5 @@ test_reroute: true test_s3: true use_issue_template: true use_legacy_docs: true -use_unified_docs: false +use_unified_docs: true