From 5f647fae54c0cbf684a5d16170923ef332cce756 Mon Sep 17 00:00:00 2001 From: Matthias Dellweg Date: Wed, 7 Aug 2024 09:40:41 +0200 Subject: [PATCH 1/2] Experiment --- .ci/scripts/validate_commit_message.py | 8 +--- .github/template_gitref | 2 +- .github/workflows/ci.yml | 4 ++ .github/workflows/create-branch.yml | 15 ++++--- .github/workflows/docs.yml | 54 ++++++++++++++++++++++++++ .github/workflows/scripts/install.sh | 17 +++----- .github/workflows/scripts/script.sh | 10 +---- .github/workflows/test.yml | 1 - doc_requirements.txt | 4 +- template_config.yml | 6 +-- 10 files changed, 76 insertions(+), 45 deletions(-) create mode 100644 .github/workflows/docs.yml diff --git a/.ci/scripts/validate_commit_message.py b/.ci/scripts/validate_commit_message.py index b254b248..0b2cb71c 100755 --- a/.ci/scripts/validate_commit_message.py +++ b/.ci/scripts/validate_commit_message.py @@ -9,21 +9,17 @@ import sys from pathlib import Path import subprocess - - import os import warnings from github import Github - NO_ISSUE = "[noissue]" CHANGELOG_EXTS = [".feature", ".bugfix", ".doc", ".removal", ".misc", ".deprecation"] +KEYWORDS = ["fixes", "closes"] + sha = sys.argv[1] message = subprocess.check_output(["git", "log", "--format=%B", "-n 1", sha]).decode("utf-8") - -KEYWORDS = ["fixes", "closes"] - g = Github(os.environ.get("GITHUB_TOKEN")) repo = g.get_repo("pulp/pulp_gem") diff --git a/.github/template_gitref b/.github/template_gitref index 9e5cdc02..178e0380 100644 --- a/.github/template_gitref +++ b/.github/template_gitref @@ -1 +1 @@ -2021.08.26-364-g6f9579c +2021.08.26-376-gba57590 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 76fc534a..9b8c9874 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -46,6 +46,9 @@ jobs: run: | python .ci/scripts/check_requirements.py + docs: + uses: "./.github/workflows/docs.yml" + lint: uses: "./.github/workflows/lint.yml" @@ -84,6 +87,7 @@ jobs: - "check-commits" - "lint" - "test" + - "docs" if: "always()" steps: - name: "Collect needed jobs results" diff --git a/.github/workflows/create-branch.yml b/.github/workflows/create-branch.yml index 1ce4948a..6ba181a0 100644 --- a/.github/workflows/create-branch.yml +++ b/.github/workflows/create-branch.yml @@ -26,6 +26,12 @@ jobs: fetch-depth: 0 path: "pulp_gem" + - uses: "actions/checkout@v4" + with: + fetch-depth: 1 + repository: "pulp/plugin_template" + path: "plugin_template" + - uses: "actions/setup-python@v5" with: python-version: "3.11" @@ -33,7 +39,7 @@ jobs: - name: "Install python dependencies" run: | echo ::group::PYDEPS - pip install bump2version jinja2 pyyaml packaging + pip install bump2version jinja2 pyyaml packaging -r plugin_template/requirements.txt echo ::endgroup:: - name: "Setting secrets" @@ -71,13 +77,6 @@ jobs: run: | find CHANGES -type f -regex ".*\.\(bugfix\|doc\|feature\|misc\|deprecation\|removal\)" -exec git rm {} + - - name: Checkout plugin template - uses: actions/checkout@v4 - with: - repository: pulp/plugin_template - path: plugin_template - fetch-depth: 0 - - name: Update CI branches in template_config working-directory: plugin_template run: | diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..2fef1c66 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,54 @@ +# WARNING: DO NOT EDIT! +# +# This file was generated by plugin_template, and is managed by it. Please use +# './plugin-template --github pulp_gem' to update this file. +# +# For more info visit https://github.com/pulp/plugin_template + +--- +name: "Docs" +on: + workflow_call: + +jobs: + test: + if: "endsWith(github.base_ref, 'main')" + runs-on: "ubuntu-20.04" + defaults: + run: + working-directory: "pulp_gem" + steps: + - uses: "actions/checkout@v4" + with: + fetch-depth: 1 + path: "pulp_gem" + - uses: "actions/setup-python@v5" + with: + python-version: "3.11" + - name: "Setup cache key" + run: | + git ls-remote https://github.com/pulp/pulp-docs main | tee pulp-docs-main-sha + - uses: "actions/cache@v4" + with: + path: "~/.cache/pip" + key: ${{ runner.os }}-pip-${{ hashFiles('pulp-docs-main-sha') }} + restore-keys: | + ${{ runner.os }}-pip- + - name: "Install python dependencies" + run: | + echo ::group::PYDEPS + pip install -r doc_requirements.txt + echo ::endgroup:: + - name: "Build changelog" + run: | + towncrier build --yes --version 4.0.0.ci + - name: "Build docs" + run: | + pulp-docs build + + no-test: + if: "!endsWith(github.base_ref, 'main')" + runs-on: "ubuntu-20.04" + steps: + - run: | + echo "Skip docs testing on non-main branches." diff --git a/.github/workflows/scripts/install.sh b/.github/workflows/scripts/install.sh index dc4cfe69..365302a5 100755 --- a/.github/workflows/scripts/install.sh +++ b/.github/workflows/scripts/install.sh @@ -21,18 +21,13 @@ PLUGIN_SOURCE="./pulp_gem/dist/pulp_gem-${PLUGIN_VERSION}-py3-none-any.whl" export PULP_API_ROOT="/pulp/" PIP_REQUIREMENTS=("pulp-cli-gem") -if [[ "$TEST" = "docs" || "$TEST" = "publish" ]] -then - PIP_REQUIREMENTS+=("-r" "doc_requirements.txt") -fi +# This must be the **only** call to "pip install" on the test runner. pip install ${PIP_REQUIREMENTS[*]} -if [[ "$TEST" != "docs" ]] -then - PULP_CLI_VERSION="$(pip freeze | sed -n -e 's/pulp-cli-gem==//p')" - git clone --depth 1 --branch "$PULP_CLI_VERSION" https://github.com/pulp/pulp-cli-gem.git ../pulp-cli-gem -fi +# Check out the pulp-cli-gem branch matching the installed version. +PULP_CLI_VERSION="$(pip freeze | sed -n -e 's/pulp-cli-gem==//p')" +git clone --depth 1 --branch "$PULP_CLI_VERSION" https://github.com/pulp/pulp-cli-gem.git ../pulp-cli-gem cd .ci/ansible/ if [ "$TEST" = "s3" ]; then @@ -126,9 +121,7 @@ if [ "${PULP_API_ROOT:-}" ]; then fi pulp config create --base-url https://pulp --api-root "$PULP_API_ROOT" --username "admin" --password "password" -if [[ "$TEST" != "docs" ]]; then - cp ~/.config/pulp/cli.toml "${REPO_ROOT}/../pulp-cli-gem/tests/cli.toml" -fi +cp ~/.config/pulp/cli.toml "${REPO_ROOT}/../pulp-cli-gem/tests/cli.toml" ansible-playbook build_container.yaml ansible-playbook start_container.yaml diff --git a/.github/workflows/scripts/script.sh b/.github/workflows/scripts/script.sh index 7225d8c3..925da273 100755 --- a/.github/workflows/scripts/script.sh +++ b/.github/workflows/scripts/script.sh @@ -18,7 +18,7 @@ source .github/workflows/scripts/utils.sh export POST_SCRIPT=$PWD/.github/workflows/scripts/post_script.sh export FUNC_TEST_SCRIPT=$PWD/.github/workflows/scripts/func_test_script.sh -# Needed for both starting the service and building the docs. +# Needed for starting the service # Gets set in .github/settings.yml, but doesn't seem to inherited by # this script. export DJANGO_SETTINGS_MODULE=pulpcore.app.settings @@ -26,14 +26,6 @@ export PULP_SETTINGS=$PWD/.ci/ansible/settings/settings.py export PULP_URL="https://pulp" -if [[ "$TEST" = "docs" ]]; then - if [[ "$GITHUB_WORKFLOW" == "Gem CI" ]]; then - towncrier build --yes --version 4.0.0.ci - fi - 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 d4aa0a9e..5e823874 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -22,7 +22,6 @@ jobs: matrix: env: - TEST: pulp - - TEST: docs - TEST: azure - TEST: s3 - TEST: lowerbounds diff --git a/doc_requirements.txt b/doc_requirements.txt index 5e17ba97..76a07a88 100644 --- a/doc_requirements.txt +++ b/doc_requirements.txt @@ -1,10 +1,8 @@ # WARNING: DO NOT EDIT! # # This file was generated by plugin_template, and is managed by it. Please use -# './plugin-template --docs pulp_gem' to update this file. +# './plugin-template --github pulp_gem' to update this file. # # For more info visit https://github.com/pulp/plugin_template --r requirements.txt towncrier - pulp-docs @ git+https://github.com/pulp/pulp-docs@main diff --git a/template_config.yml b/template_config.yml index 79899c5a..7534f6e8 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-364-g6f9579c +# generated with plugin_template@2021.08.26-376-gba57590 api_root: /pulp/ black: true @@ -12,7 +12,6 @@ check_stray_pulpcore_imports: true ci_base_image: ghcr.io/pulp/pulp-ci-centos9 ci_env: {} ci_trigger: '{pull_request: {branches: [''*'']}}' -ci_update_docs: true cli_package: pulp-cli-gem cli_repo: https://github.com/pulp/pulp-cli-gem.git core_import_allowed: [] @@ -20,13 +19,10 @@ deploy_client_to_pypi: true deploy_client_to_rubygems: true deploy_to_pypi: true disabled_redis_runners: [] -doc_requirements_from_pulpcore: false docker_fixtures: false -docs_test: true flake8: true flake8_ignore: [] github_org: pulp -issue_tracker: github latest_release_branch: '0.6' lint_requirements: true noissue_marker: '[noissue]' From 9e72eaf85a10b11913120700acaee99179ff7b51 Mon Sep 17 00:00:00 2001 From: Matthias Dellweg Date: Wed, 7 Aug 2024 09:45:54 +0200 Subject: [PATCH 2/2] Remove docs litter --- docs/Makefile | 199 ----------------------------------- docs/_templates/restapi.html | 24 ----- docs/changes.rst | 4 - docs/static/.gitkeep | 0 docs/template_gitref | 1 - 5 files changed, 228 deletions(-) delete mode 100644 docs/Makefile delete mode 100644 docs/_templates/restapi.html delete mode 100644 docs/changes.rst delete mode 100644 docs/static/.gitkeep delete mode 100644 docs/template_gitref diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 248471d4..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,199 +0,0 @@ -# WARNING: DO NOT EDIT! -# -# This file was generated by plugin_template, and is managed by it. Please use -# './plugin-template --docs pulp_gem' 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 # turn warnings into errors -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build -DIAGRAM_BUILD_DIR = _diagrams -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 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" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -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 diagrams_src), ) - mkdir -p $(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 - -$(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=gem&include_html=1"; \ - else \ - curl --fail -o $(BUILDDIR)/html/api.json "$(PULP_V3_API_JSON_URL)?plugin=pulp_gem&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: -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." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -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." - -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 - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/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)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/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)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -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." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "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 deleted file mode 100644 index 1ae844fa..00000000 --- a/docs/_templates/restapi.html +++ /dev/null @@ -1,24 +0,0 @@ - - - - REST API for Pulp 3 gem Plugin - - - - - - - - - - - - - diff --git a/docs/changes.rst b/docs/changes.rst deleted file mode 100644 index 96e8eb90..00000000 --- a/docs/changes.rst +++ /dev/null @@ -1,4 +0,0 @@ -Changes -********* - -Removed due to docs migration process. diff --git a/docs/static/.gitkeep b/docs/static/.gitkeep deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/template_gitref b/docs/template_gitref deleted file mode 100644 index 9e5cdc02..00000000 --- a/docs/template_gitref +++ /dev/null @@ -1 +0,0 @@ -2021.08.26-364-g6f9579c