docs: use sphinx-gitref to handle git links dynamically

[mjpieters]

Fix #459

Proposed changes

Use sphinx-gitref to generate github links to the project.

This automatically handles references to nitpick GitHub files based on the current checked out branch, including on ReadTheDocs. This takes care of the vast majority of project references.

There are a few caveats:

• Currently the links always go to a branch, never a tag. There are no tag-specific RTD documentation pages however. If this were to change in future can link to a specific tag by settin the gitref_branch configuration item to the tag name in the docs/conf.py configuration, when, say, the READTHEDOCS_VERSION env variable is set to a specific version rather than latest or stable.
• I changed the remaining hard-coded reference in the README.rst file to use a relative path, same as what the auto-generated style-library section was already using. These links will break when pushed to PyPI. This was already a problem before this change, however.
• There are two hard-coded links left, in the Configuration section of the documentation. Both are code-block examples on how to use regular GitHub URLs. These are just examples so may be just fine.

The issue with the README.rst links being relative should probably only be addressed when releasing to PyPI; at that point the README.rst links could be updated to include the specific release tag before packaging, either as part of the release commit or as a poetry plugin that runs during wheel and sdist builds.

Checklist

• Read the contribution guidelines
• Run make locally before pushing commits

[mjpieters]

I see the 3.9 tests failed to find git info:

Handler <function lookup_remote at 0x7f22b53174c0> for event 'config-inited' threw an exception (exception: Could not determine gitref_branch, must set explicitly)

and that only 3.9 runs the docs update (from the workflow):

      - name: "Set lint/docs env var"
        if: matrix.python-version == '3.9'
        run: |
          echo "LINT_DOCS=,lint,docs" >> $GITHUB_ENV

I'll try to make time for this tomorrow or Monday.

[coveralls]

Pull Request Test Coverage Report for Build 2017668936

• 0 of 0 changed or added relevant lines in 0 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 96.856%

---

Totals
Change from base Build 2010411333:	0.0%
Covered Lines:	2041
Relevant Lines:	2089

---

💛 - Coveralls

[andreoliwa]

I see the 3.9 tests failed to find git info:

Handler <function lookup_remote at 0x7f22b53174c0> for event 'config-inited' threw an exception (exception: Could not determine gitref_branch, must set explicitly)

I fixed the broken build by setting the version as the Git branch.

I don't know if the links will be broken, I will take a look at GitHub Actions logs later.

[andreoliwa]

Unrelated to your changes, I also fixed some Sphinx warnings from extlinks.

I left a comment to hear your opinion on the (hacky) workaround I suggested for gitref_branch.

[mjpieters]

Hrm, weird. I would have expected this to pass now.

I was basing this on the documentation of GH default environment variables:

Environment variable	Description
...	...
GITHUB_ACTIONS	Always set to true when GitHub Actions is running the workflow. You can use this variable to differentiate when tests are being run locally or by GitHub Actions.
GITHUB_REF_NAME	The branch or tag name that triggered the workflow run. For example, feature-branch-1.

When the PR runs, GITHUB_ACTIONS is not set? Perhaps we need to pass this through to tox.

[mjpieters]

When the PR runs, GITHUB_ACTIONS is not set? Perhaps we need to pass this through to tox.

Confirmed. I've added a new commit that adds a passenv entry for the docs tox environment, and also updates the bumpversion config.

[andreoliwa]

Thanks for solving it! 🙏🏻

[github-actions]

🎉 This PR is included in version 0.32.0 🎉

The release is available on:

• v0.32.0
• GitHub release

Your semantic-release bot 📦🚀