From 69410a387fec1386968ae58c51f4951105476645 Mon Sep 17 00:00:00 2001 From: Jean-Christophe Morin <38703886+JeanChristopheMorinPerso@users.noreply.github.com> Date: Fri, 17 Nov 2023 20:58:33 -0500 Subject: [PATCH] Add changelog to docs and fix external links (#68) Signed-off-by: Jean-Christophe Morin --- .github/workflows/ci.yaml | 2 + .github/workflows/docs.yaml | 111 ++++++++++++++++++++++++++++++++++++ CHANGELOG.md | 24 ++++---- docs/Makefile | 12 +++- docs/make.bat | 2 +- docs/requirements.txt | 1 + docs/source/changelog.md | 5 ++ docs/source/conf.py | 58 +++++++++++++++++++ docs/source/index.rst | 5 +- docs/source/transition.rst | 6 +- docs/source/user_guide.rst | 7 +-- 11 files changed, 208 insertions(+), 25 deletions(-) create mode 100644 .github/workflows/docs.yaml create mode 100644 docs/source/changelog.md diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 1d38797..b3ee9ae 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -7,11 +7,13 @@ on: - .github/workflows/update_pip.yaml - docs/** - .readthedocs.yaml + - '**/*.md' pull_request: paths-ignore: - .github/workflows/update_pip.yaml - docs/** - .readthedocs.yaml + - '**/*.md' concurrency: cancel-in-progress: true diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000..866a9ae --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,111 @@ +name: docs + +on: + push: + paths: + - '**/CHANGELOG.md' + - 'docs/**' + - '.github/workflows/docs.yaml' + pull_request: + paths: + - '**/CHANGELOG.md' + - 'docs/**' + - '.github/workflows/docs.yaml' + +jobs: + check-links: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + submodules: 'recursive' + + - uses: actions/setup-python@v4.3.0 + with: + python-version: '3.11' + + - name: Create virtualenv + run: python3 -m venv .venv + + - name: Install dependencies + run: | + source .venv/bin/activate + python -m pip install . + python -m pip install -r docs/requirements.txt + + - name: Linkcheck + working-directory: docs + run: | + source ../.venv/bin/activate + + set +e + make linkcheck + exit_code=$? + + set -e + + if [ $exit_code -eq 0 ]; then + echo -e "\n\n=================\nAll links are valid!" + + echo "# :heavy_check_mark: Sphinx links" >> $GITHUB_STEP_SUMMARY + echo "All links are valid!" >> $GITHUB_STEP_SUMMARY + else + echo -e "\n\n=================\nFound broken links. Look at the build logs.\n" + + echo "# :x: Sphinx links" >> $GITHUB_STEP_SUMMARY + echo "Found broken links. Look at the build logs for additional information." >> $GITHUB_STEP_SUMMARY + echo '```' >> $GITHUB_STEP_SUMMARY + cat build/linkcheck/output.txt >> $GITHUB_STEP_SUMMARY + echo '```' >> $GITHUB_STEP_SUMMARY + fi + + exit $exit_code + + check-warnings: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + submodules: 'recursive' + + - uses: actions/setup-python@v4.3.0 + with: + python-version: '3.11' + + - name: Create virtualenv + run: python3 -m venv .venv + + - name: Install dependencies + run: | + source .venv/bin/activate + python -m pip install . + python -m pip install -r docs/requirements.txt + + - name: Check warnings/errors + working-directory: docs + run: | + source ../.venv/bin/activate + + set +e + make htmlstrict + + exit_code=$? + + set -e + + if [ $exit_code -eq 0 ]; then + echo -e "\n\n=================\nNo warnings or errors detected!" + echo "# :heavy_check_mark: Sphinx warnings/errors" >> $GITHUB_STEP_SUMMARY + echo "No errors or warnings detected!" >> $GITHUB_STEP_SUMMARY + else + echo -e "\n\n=================\nWarnings and or errors detected; See the summary bellow:\n" + cat _build/htmlstrict/output.txt + + echo "# :x: Sphinx warnings/errors" >> $GITHUB_STEP_SUMMARY + echo "Found some warnings or errors:" >> $GITHUB_STEP_SUMMARY + echo '```' >> $GITHUB_STEP_SUMMARY + cat _build/htmlstrict/output.txt >> $GITHUB_STEP_SUMMARY + echo '```' >> $GITHUB_STEP_SUMMARY + fi + + exit $exit_code diff --git a/CHANGELOG.md b/CHANGELOG.md index 4852c5e..a521ba4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,22 +1,26 @@ -# 0.3.1 (2023-11-17) +# Changelog -* Fix decoding error when reading pip dependency report. See [PR #63](https://github.com/JeanChristopheMorinPerso/rez-pip/pull/63). -* Update vendored pip from 23.2.1 to 23.3.1 + -# 0.3.0 (2023-10-12) +## 0.3.1 (2023-11-17) + +* Fix decoding error when reading pip dependency report (#63). +* Update vendored pip from 23.2.1 to 23.3.1. + +## 0.3.0 (2023-10-12) Most notable changes: -* Don't append system PATH to context when finding the python executables (#47) -* Update pip from 23.1.2 to 23.2 (#44) -* Ensure Windows short paths are resolved to long paths (#50) -* Read rez-pip version from distribution metadata (#53) +* Don't append system PATH to context when finding the python executables (#47). +* Update pip from 23.1.2 to 23.2 (#44). +* Ensure Windows short paths are resolved to long paths (#50). +* Read rez-pip version from distribution metadata (#53). -# 0.2.0 (2023-07-04) +## 0.2.0 (2023-07-04) This release fixes a lot of bugs and gets us closer to a more official release. Most notable changes: -* Dropped support for installing Python 2 packages. Python 3.7+ is supported. See [PR #39](https://github.com/JeanChristopheMorinPerso/rez-pip/pull/39). +* Dropped support for installing Python 2 packages. Python 3.7+ is supported (#39). * A lot more documentation. It now includes a transition guide, a user guide, information on the metadata conversion process, etc. * The command line arguments have been cleaned up (`--install-path` renamed to `--prefix`, `--release` was added, etc). * A lightweigth weehl cache was added to avoid re-downloading the same wheel for multiple python versions. diff --git a/docs/Makefile b/docs/Makefile index 790e03f..92507f1 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -3,7 +3,7 @@ # You can set these variables from the command line, and also # from the environment for the first two. -SPHINXOPTS ?= +SPHINXOPTS ?= -n SPHINXBUILD ?= sphinx-build SOURCEDIR = source BUILDDIR = build @@ -12,7 +12,7 @@ BUILDDIR = build help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile +.PHONY: help Makefile htmlstrict livehtml: sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) @@ -20,4 +20,10 @@ livehtml: # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: htmlstrict +htmlstrict: + $(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" -W --keep-going -w $(BUILDDIR)/htmlstrict/output.txt + @echo + @echo "Warnings check complete." diff --git a/docs/make.bat b/docs/make.bat index 747ffb7..7b6551e 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -25,7 +25,7 @@ if errorlevel 9009 ( if "%1" == "" goto help -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% -n %O% goto end :help diff --git a/docs/requirements.txt b/docs/requirements.txt index 9131424..3082493 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -2,3 +2,4 @@ sphinx ~= 7.2 furo sphinx-autobuild sphinx-inline-tabs +myst-parser diff --git a/docs/source/changelog.md b/docs/source/changelog.md new file mode 100644 index 0000000..6b4af78 --- /dev/null +++ b/docs/source/changelog.md @@ -0,0 +1,5 @@ +# Changelog + +```{include} ../../CHANGELOG.md +:start-after: +``` diff --git a/docs/source/conf.py b/docs/source/conf.py index d53701d..201d561 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -3,6 +3,11 @@ # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +from sphinx.application import Sphinx +from sphinx.transforms import SphinxTransform +from docutils.nodes import reference, Text +import re + # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information @@ -21,6 +26,7 @@ "sphinx.ext.autosectionlabel", # Third-part "sphinx_inline_tabs", + "myst_parser", ] templates_path = ["_templates"] @@ -33,7 +39,59 @@ html_theme = "furo" html_static_path = ["_static"] + # -- Options for sphinx.ext.autosectionlabel --------------------------------- # https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html autosectionlabel_prefix_document = True + + +# -- Options for the linkcheck builder --------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder + +linkcheck_allowed_redirects = { + r"https://github.com/JeanChristopheMorinPerso/rez-pip/issues/\d+": "https://github.com/JeanChristopheMorinPerso/rez-pip/pull/\d+" +} + + +# -- Options for sphinx.ext.intersphinx_mapping ------------------------------ +# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html + +intersphinx_mapping = { + "rez": ("https://rez.readthedocs.io/en/stable/", None), +} + +# Force usage of :external: +intersphinx_disabled_reftypes = ["*"] + + +# -- Custom ------------------------------------------------------------------ +# Custom stuff + + +class ReplaceGHRefs(SphinxTransform): + default_priority = 750 + prefix = "https://github.com/JeanChristopheMorinPerso/rez-pip/issues" + + def apply(self): + istext = lambda o: isinstance(o, Text) + + for node in self.document.traverse(istext): + match = re.match(r".*\((\#(\d+))\)\.?$", str(node)) + if not match: + continue + + newtext = Text(str(node)[: match.start(1)]) + newreference = reference( + "", match.group(1), refuri=f"{self.prefix}/{match.group(2)}" + ) + trailingtext = Text(str(node)[match.end(1) :]) + node.parent.replace(node, newtext) + node.parent.insert(node.parent.index(newtext) + 1, newreference) + node.parent.insert(node.parent.index(newtext) + 2, trailingtext) + + return + + +def setup(app: Sphinx): + app.add_transform(ReplaceGHRefs) diff --git a/docs/source/index.rst b/docs/source/index.rst index 75f81df..eb7848c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -35,7 +35,7 @@ Installation ``rez-pip`` can be installed by using pip. We highly recommend that you install it into your rez's virtual environment (the virtualenv that is -automatically created by the `install.py `_ script). +automatically created by the `install.py `_ script). .. tab:: Linux/macOS @@ -68,4 +68,5 @@ automatically created by the `install.py