From d5a64a6b249fa71259ab310056633ca5aa76b0c9 Mon Sep 17 00:00:00 2001 From: Matthias Dellweg Date: Mon, 18 Sep 2023 11:45:18 +0200 Subject: [PATCH] Update CI, enable docs template [noissue] --- .ci/scripts/changelog.py | 70 -------------- .github/dependabot.yml | 7 -- .github/template_gitref | 2 +- .github/workflows/changelog.yml | 4 +- .github/workflows/ci.yml | 16 ++-- .github/workflows/create-branch.yml | 32 ++++--- .github/workflows/nightly.yml | 16 ++-- .github/workflows/release.yml | 8 +- .github/workflows/scripts/install.sh | 2 - .github/workflows/update-labels.yml | 2 +- .github/workflows/update_ci.yml | 2 +- doc_requirements.txt | 20 ++-- docs/Makefile | 78 +++++++++++---- ...s_makes_it_so_git_keeps_the__static_folder | 1 - docs/_templates/restapi.html | 2 +- docs/conf.py | 95 ++++++++++++++++--- docs/static/.gitkeep | 0 docs/template_gitref | 1 + template_config.yml | 8 +- 19 files changed, 201 insertions(+), 165 deletions(-) delete mode 100755 .ci/scripts/changelog.py delete mode 100644 docs/_static/.this_makes_it_so_git_keeps_the__static_folder mode change 100644 => 100755 docs/conf.py create mode 100644 docs/static/.gitkeep create mode 100644 docs/template_gitref diff --git a/.ci/scripts/changelog.py b/.ci/scripts/changelog.py deleted file mode 100755 index 25422f3..0000000 --- a/.ci/scripts/changelog.py +++ /dev/null @@ -1,70 +0,0 @@ -import re -import os -import requests -from packaging.version import Version -from git import Repo - -repo = Repo(os.getcwd()) -heads = repo.git.ls_remote("--heads", "https://github.com/pulp/pulp_maven.git").split("\n") -branches = [h.split("/")[-1] for h in heads if re.search(r"^([0-9]+)\.([0-9]+)$", h.split("/")[-1])] -branches.sort(key=lambda ver: Version(ver), reverse=True) - - -def get_changelog(branch): - """ - Get changelog file for a given branch. - - """ - return requests.get( - f"https://raw.githubusercontent.com/pulp/pulp_maven/{branch}/CHANGES.rst" - ).text - - -def get_changelog_releases(changelog): - """ - Get all versions in changelog. - - """ - versions = re.findall( - r"([0-9]+)\.([0-9]+)\.([0-9][0-9ab]*) \([0-9]{4}-[0-9]{2}-[0-9]{2}\)", changelog - ) - return {".".join(v) for v in versions} - - -def get_changelog_entry(changelog, version): - """ - Get changelog entry for a given version. - - """ - entries = changelog.split(f"{version} (")[1].split("=====\n") - header = f"{version} ({entries[0]}=====\n" - text = "\n\n\n".join(entries[1].split("\n\n\n")[0:-1]) - return header + text + "\n\n\n" - - -main_changelog = get_changelog("main") -main_entries = get_changelog_releases(main_changelog) -entries_list = list(main_entries) -to_add = {} -for branch in branches: - changelog = get_changelog(branch) - entries = get_changelog_releases(changelog) - for entry in entries.difference(main_entries): - description = get_changelog_entry(changelog, entry) - entries_list.append(entry) - print(description) - to_add[entry] = description - -entries_list.sort(key=lambda ver: Version(ver), reverse=True) -for version in sorted(to_add, key=lambda ver: Version(ver)): - next_version = entries_list[entries_list.index(version) + 1] - new_changelog = main_changelog.split(f"{next_version} (")[0] + to_add[version] - new_changelog = new_changelog + f"{next_version} (" - new_changelog = new_changelog + main_changelog.split(f"{next_version} (")[1] - main_changelog = new_changelog - -with open("CHANGES.rst", "w") as f: - f.write(main_changelog) - -if to_add: - repo.git.commit("-m", "Update Changelog\n\n[noissue]", "CHANGES.rst") diff --git a/.github/dependabot.yml b/.github/dependabot.yml index fba8440..323bc22 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -7,10 +7,3 @@ updates: open-pull-requests-limit: 10 commit-message: prefix: "[noissue]" -- package-ecosystem: github-actions - directory: "/" - schedule: - interval: daily - open-pull-requests-limit: 10 - commit-message: - prefix: "[noissue]" diff --git a/.github/template_gitref b/.github/template_gitref index 82904ba..c208a73 100644 --- a/.github/template_gitref +++ b/.github/template_gitref @@ -1 +1 @@ -2021.08.26-246-g98b439a +2021.08.26-247-g1ee39ae diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml index cf280e9..16b8977 100644 --- a/.github/workflows/changelog.yml +++ b/.github/workflows/changelog.yml @@ -24,11 +24,11 @@ jobs: fail-fast: false steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 with: fetch-depth: 1 - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 with: python-version: "3.8" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7eecdf1..6be7eaf 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -18,10 +18,10 @@ jobs: ready-to-ship: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 with: fetch-depth: 0 - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 with: python-version: "3.8" - name: Install requirements @@ -45,7 +45,7 @@ jobs: name: Assert single commit if: github.base_ref == 'main' steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Checkout main @@ -59,10 +59,10 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 with: fetch-depth: 1 - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 with: python-version: "3.8" # lint_requirements contains tools needed for flake8, etc. @@ -112,11 +112,11 @@ jobs: deprecations-lowerbounds: ${{ steps.deprecations.outputs.deprecations-lowerbounds }} steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 with: fetch-depth: 1 - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 with: python-version: "3.8" @@ -169,7 +169,7 @@ jobs: GITHUB_REPO_SLUG: ${{ github.repository }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} GITHUB_CONTEXT: ${{ github.event.pull_request.commits_url }} - REDIS_DISABLED: ${{ contains('', matrix.env.TEST) }} + REDIS_DISABLED: ${{ contains('s3', matrix.env.TEST) }} - name: Setting secrets if: github.event_name != 'pull_request' diff --git a/.github/workflows/create-branch.yml b/.github/workflows/create-branch.yml index 11460e9..1000ed8 100644 --- a/.github/workflows/create-branch.yml +++ b/.github/workflows/create-branch.yml @@ -9,10 +9,6 @@ name: Create New Release Branch on: workflow_dispatch: - inputs: - name: - description: "Branch name (e.g. 3.14)" - required: true env: RELEASE_WORKFLOW: true @@ -25,12 +21,12 @@ jobs: fail-fast: false steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 with: - fetch-depth: 1 + fetch-depth: 0 path: pulp_maven - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 with: python-version: "3.8" @@ -46,26 +42,27 @@ jobs: env: SECRETS_CONTEXT: ${{ toJson(secrets) }} - - name: Verify that branch name matches current version string on main branch + - name: Determine new branch name working-directory: pulp_maven run: | - X_Y_VERSION=$(grep version setup.py | sed -rn 's/version="(.*)\.0((a[0-9]+)|(b[0-9]+))?\.dev",/\1/p' | awk '{$1=$1};1') - if [[ "$X_Y_VERSION" != "${{ inputs.name }}" ]] + # Just to be sure... + git checkout main + NEW_BRANCH="$(bump2version --dry-run --list release | sed -Ene 's/^new_version=([[:digit:]]+\.[[:digit:]]+)\..*$/\1/p')" + if [ -z "$NEW_BRANCH" ] then - echo "Branch name doesn't match the current version string $X_Y_VERSION." + echo Could not determine the new branch name. exit 1 fi + echo "NEW_BRANCH=${NEW_BRANCH}" >> "$GITHUB_ENV" - - name: Create ${{ inputs.name }} release branch + - name: Create release branch working-directory: pulp_maven run: | - git checkout -b ${{ inputs.name }} - git push origin ${{ inputs.name }} + git branch "${NEW_BRANCH}" - name: Bump version on main branch working-directory: pulp_maven run: | - git checkout main bump2version --no-commit minor - name: Remove entries from CHANGES directory @@ -88,3 +85,8 @@ jobs: Bump minor version [noissue] delete-branch: true + + - name: Push release branch + working-directory: pulp_maven + run: | + git push origin "${NEW_BRANCH}" diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index 1552ffd..55d10c2 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -35,11 +35,11 @@ jobs: - TEST: lowerbounds steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 with: fetch-depth: 1 - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 with: python-version: "3.8" @@ -97,7 +97,7 @@ jobs: GITHUB_REPO_SLUG: ${{ github.repository }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} GITHUB_CONTEXT: ${{ github.event.pull_request.commits_url }} - REDIS_DISABLED: ${{ contains('', matrix.env.TEST) }} + REDIS_DISABLED: ${{ contains('s3', matrix.env.TEST) }} - name: Setting secrets run: python3 .github/workflows/scripts/secrets.py "$SECRETS_CONTEXT" @@ -168,11 +168,11 @@ jobs: changelog: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 with: fetch-depth: 0 - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 with: python-version: "3.11" @@ -207,11 +207,11 @@ jobs: TEST: publish steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 with: fetch-depth: 1 - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 with: python-version: "3.8" @@ -282,7 +282,7 @@ jobs: GITHUB_REPO_SLUG: ${{ github.repository }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} GITHUB_CONTEXT: ${{ github.event.pull_request.commits_url }} - REDIS_DISABLED: ${{ contains('', matrix.env.TEST) }} + REDIS_DISABLED: ${{ contains('s3', matrix.env.TEST) }} - name: Setting secrets run: python3 .github/workflows/scripts/secrets.py "$SECRETS_CONTEXT" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 55a9402..2b43ea7 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -30,11 +30,11 @@ jobs: fail-fast: false steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 with: fetch-depth: 0 - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 with: python-version: "3.8" @@ -79,7 +79,7 @@ jobs: with: name: pulp_maven.tar - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 with: python-version: "3.8" - uses: ruby/setup-ruby@v1 @@ -201,7 +201,7 @@ jobs: with: name: pulp_maven.tar - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 with: python-version: "3.8" diff --git a/.github/workflows/scripts/install.sh b/.github/workflows/scripts/install.sh index c2a9caf..a85d5aa 100755 --- a/.github/workflows/scripts/install.sh +++ b/.github/workflows/scripts/install.sh @@ -21,8 +21,6 @@ PIP_REQUIREMENTS=("pulp-cli-maven") if [[ "$TEST" = "docs" || "$TEST" = "publish" ]] then PIP_REQUIREMENTS+=("-r" "doc_requirements.txt") - git clone https://github.com/pulp/pulpcore.git ../pulpcore - PIP_REQUIREMENTS+=("psycopg2-binary" "-r" "../pulpcore/doc_requirements.txt") fi pip install ${PIP_REQUIREMENTS[*]} diff --git a/.github/workflows/update-labels.yml b/.github/workflows/update-labels.yml index 0d2b6ee..a2ae9ac 100644 --- a/.github/workflows/update-labels.yml +++ b/.github/workflows/update-labels.yml @@ -19,7 +19,7 @@ jobs: update_backport_labels: runs-on: ubuntu-latest steps: - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 with: python-version: "3.8" - name: Configure Git with pulpbot name and email diff --git a/.github/workflows/update_ci.yml b/.github/workflows/update_ci.yml index dbb0beb..9c90deb 100644 --- a/.github/workflows/update_ci.yml +++ b/.github/workflows/update_ci.yml @@ -30,7 +30,7 @@ jobs: path: plugin_template fetch-depth: 0 - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 with: python-version: "3.8" diff --git a/doc_requirements.txt b/doc_requirements.txt index 8a111cc..9ce6fa2 100644 --- a/doc_requirements.txt +++ b/doc_requirements.txt @@ -1,11 +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_maven' to update this file. +# +# For more info visit https://github.com/pulp/plugin_template +-r requirements.txt plantuml -pyyaml -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 91cee3b..53dca1c 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,27 +1,37 @@ +# WARNING: DO NOT EDIT! +# +# This file was generated by plugin_template, and is managed by it. Please use +# './plugin-template --docs pulp_maven' 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 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" @@ -45,25 +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: - curl --fail -o _static/api.json "$(PULP_URL)/pulp/api/v3/docs/api.json?plugin=pulp_maven&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_maven&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." @@ -86,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 @@ -98,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 @@ -121,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 @@ -143,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/_static/.this_makes_it_so_git_keeps_the__static_folder b/docs/_static/.this_makes_it_so_git_keeps_the__static_folder deleted file mode 100644 index 8b13789..0000000 --- a/docs/_static/.this_makes_it_so_git_keeps_the__static_folder +++ /dev/null @@ -1 +0,0 @@ - diff --git a/docs/_templates/restapi.html b/docs/_templates/restapi.html index 6e137eb..2ffc278 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 60bf647..bcd534d --- 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_maven' 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'] +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'] @@ -43,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 maven 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 0000000..e69de29 diff --git a/docs/template_gitref b/docs/template_gitref new file mode 100644 index 0000000..a0913e5 --- /dev/null +++ b/docs/template_gitref @@ -0,0 +1 @@ +2021.08.26-247-g2270d92 diff --git a/template_config.yml b/template_config.yml index 5041ebd..f6e0965 100644 --- a/template_config.yml +++ b/template_config.yml @@ -1,7 +1,6 @@ # 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 additional_repos: [] api_root: /pulp/ @@ -13,7 +12,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-maven cli_repo: https://github.com/pulp/pulp-cli-maven.git @@ -21,8 +20,9 @@ core_import_allowed: [] deploy_client_to_pypi: true deploy_client_to_rubygems: true deploy_to_pypi: true -disabled_redis_runners: [] -doc_requirements_from_pulpcore: true +disabled_redis_runners: +- s3 +doc_requirements_from_pulpcore: false docker_fixtures: false docs_test: true extra_docs_requirements: []