From 962e61a2cb5fb07ed09753a256dbe953e7fdadc1 Mon Sep 17 00:00:00 2001 From: Lubos Mjachky Date: Tue, 12 Sep 2023 13:00:40 +0200 Subject: [PATCH] Update docs template [noissue] --- .../workflows/scripts/post_before_install.sh | 4 + doc_requirements.txt | 15 ++- docs/Makefile | 80 ++++++++++++---- docs/_templates/restapi.html | 2 +- docs/conf.py | 93 ++++++++++++++++--- docs/static/.gitkeep | 0 docs/template_gitref | 2 +- template_config.yml | 4 +- 8 files changed, 162 insertions(+), 38 deletions(-) create mode 100644 .github/workflows/scripts/post_before_install.sh create mode 100644 docs/static/.gitkeep diff --git a/.github/workflows/scripts/post_before_install.sh b/.github/workflows/scripts/post_before_install.sh new file mode 100644 index 00000000..7586a068 --- /dev/null +++ b/.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 diff --git a/doc_requirements.txt b/doc_requirements.txt index 26e8f2ee..6ce3439d 100644 --- a/doc_requirements.txt +++ b/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 diff --git a/docs/Makefile b/docs/Makefile index 09be811a..7fb1d684 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_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 ' 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 - # 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 diff --git a/docs/_templates/restapi.html b/docs/_templates/restapi.html index 636e0e7f..7d33c1e7 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 index ed4e9351..2856325b 100755 --- a/docs/conf.py +++ b/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 # " v 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) 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 index 1cb22e6b..2a9aa1bc 100644 --- a/docs/template_gitref +++ b/docs/template_gitref @@ -1 +1 @@ -2021.04.08-75-gc58df11 +2021.08.26-244-g7bb934c diff --git a/template_config.yml b/template_config.yml index 9a5caaaa..0f5458ea 100644 --- a/template_config.yml +++ b/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