Add changelog to docs and fix external links (#68)

Signed-off-by: Jean-Christophe Morin <[email protected]>
JeanChristopheMorinPerso · Nov 18, 2023 · 69410a3 · 69410a3
1 parent 26ce215
commit 69410a3
Show file tree

Hide file tree

Showing 11 changed files with 208 additions and 25 deletions.
diff --git 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
@@ -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/[email protected]
+      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/[email protected]
+      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
@@ -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
+<!-- start-here-sphinx-start-after -->
 
-# 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
@@ -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,12 +12,18 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help Makefile htmlstrict
 
 livehtml:
 	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 # 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
@@ -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
@@ -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
@@ -0,0 +1,5 @@
+# Changelog
+
+```{include} ../../CHANGELOG.md
+:start-after: <!-- start-here-sphinx-start-after -->
+```
diff --git 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
@@ -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 <https://github.com/AcademySoftwareFoundation/rez/blob/master/install.py>`_ script).
+automatically created by the `install.py <https://github.com/AcademySoftwareFoundation/rez/blob/main/install.py>`_ script).
 
 .. tab:: Linux/macOS
 
@@ -68,4 +68,5 @@ automatically created by the `install.py <https://github.com/AcademySoftwareFoun
    user_guide
    transition
    metadata
-   faq.rst
+   faq
+   changelog
diff --git a/docs/source/transition.rst b/docs/source/transition.rst
@@ -25,12 +25,10 @@ package (positional) package(**s**) (positional) Now accepts multiple packages.
 ``--pip-version``    ``--pip``                   Pip is now bundled with rez-pip, but ``--pip`` can be used to specify a different pip zipapp.
 ``-i``/``--install`` Removed
 ``-r``/``--release`` Identical
-``-p``/``--prefix``  ``--prefix``                Defaults to `local_packages_path`_.
+``-p``/``--prefix``  ``--prefix``                Defaults to :external:data:`local_packages_path`.
 ``-e``/``--extra``   ``--``                      ``--extra`` was replaced with trailing ``--``. For example ``rez-pip ... -- --index-url https://example.com``
 ==================== =========================== =======
 
-.. _local_packages_path: https://github.com/AcademySoftwareFoundation/rez/wiki/Configuring-Rez#local_packages_path
-
 Local and editable installs
 ===========================
 
@@ -43,7 +41,7 @@ I believe these functionalities would be better implemented and would better ser
 users if implemented as a `build_system`_ plugin. It would allow for better integration
 with rez and the user experience would be significantly better than it could with ``rez-pip``.
 
-.. _build_system: https://github.com/AcademySoftwareFoundation/rez/tree/master/src/rezplugins/build_system
+.. _build_system: https://github.com/AcademySoftwareFoundation/rez/tree/main/src/rezplugins/build_system
 
 I also believe that python packaging/rez hybrids are bad and just causes more issues than
 they solve. The python packaging ecosystem and tools have different objectives and goals

diff --git a/docs/source/user_guide.rst b/docs/source/user_guide.rst
@@ -15,13 +15,10 @@ so you can use it multiple times to install from multiple requriement files.
 The ``-c``/``--constraint`` argument is also available and can also be used multiple times.
 
 .. note::
-   By default, rez-pip will install packages in your configured `local_packages_path`_.
-   To install in your `release_packages_path`_,
+   By default, rez-pip will install packages in your configured :external:data:`local_packages_path`.
+   To install in your :external:data:`release_packages_path`,
    use the ``--release`` command line argument.
 
-.. _local_packages_path: https://github.com/AcademySoftwareFoundation/rez/wiki/Configuring-Rez#local_packages_path
-.. _release_packages_path: https://github.com/AcademySoftwareFoundation/rez/wiki/Configuring-Rez#release_packages_path
-
 Selecting the python version
 ============================