docs: use sphinx-gitref to handle git links dynamically

README.rst

@@ -363,8 +363,7 @@ with at least one Python (``.py``) file::
 
     flake8 .
 
-Nitpick will download and use the opinionated `default style
-file <https://github.com/andreoliwa/nitpick/blob/v0.31.0/nitpick-style.toml>`_.
+Nitpick will download and use the opinionated `default style file <nitpick-style.toml>`_.
 
 You can use it as a template to configure your own style.
 

docs/autofix_docs.py

@@ -19,10 +19,8 @@
 import click
 from slugify import slugify
 
-from nitpick import PROJECT_NAME, __version__
-from nitpick.constants import CONFIG_FILES, DOT, EDITOR_CONFIG, PROJECT_OWNER, PYLINTRC, READ_THE_DOCS_URL, SETUP_CFG
+from nitpick.constants import CONFIG_FILES, DOT, EDITOR_CONFIG, PYLINTRC, READ_THE_DOCS_URL, SETUP_CFG
 from nitpick.core import Nitpick
-from nitpick.style.fetchers.github import GitHubURL
 from nitpick.style.fetchers.pypackage import BuiltinStyle, builtin_styles
 
 RST_DIVIDER_FROM_HERE = ".. auto-generated-from-here"
@@ -283,17 +281,18 @@ class StyleLibraryRow:  # pylint: disable=too-few-public-methods
     name: str
 
 
-def _build_library(url: str = "") -> List[str]:
+def _build_library(gitref: bool = True) -> List[str]:
     # pylint: disable=no-member
     library: Dict[str, List[Tuple]] = defaultdict(list)
+    pre, post = (":gitref:", "") if gitref else ("", "_")
     for path in sorted(builtin_styles()):  # type: Path
         style = BuiltinStyle.from_path(path)
 
         # When run with tox (invoke ci-build), the path starts with "site-packages"
         clean_root = style.path_from_repo_root.replace("site-packages/", "src/")
 
         row = StyleLibraryRow(
-            style=f"`{style.py_url_without_ext} <{url + clean_root}>`_",
+            style=f"{pre}`{style.py_url_without_ext} <{clean_root}>`{post}",
             name=f"`{style.name} <{style.url}>`_" if style.url else style.name,
         )
         library[style.identify_tag].append(attr.astuple(row))
@@ -315,11 +314,10 @@ def _build_library(url: str = "") -> List[str]:
 
 def write_style_library(divider: str) -> int:
     """Write the style library table."""
-    lines = _build_library()
+    lines = _build_library(gitref=False)
     rv = DocFile("../README.rst").write(lines, divider)
 
-    url = GitHubURL(PROJECT_OWNER, PROJECT_NAME, f"v{__version__}", "", "").url
-    lines = _build_library(url)
+    lines = _build_library()
     rv += DocFile("library.rst").write(lines)
     return rv
 

docs/conf.py

@@ -54,6 +54,8 @@
     "sphinx.ext.todo",
     # http://www.sphinx-doc.org/en/master/usage/extensions/viewcode.html
     "sphinx.ext.viewcode",
+    # https://github.com/wildfish/sphinx-gitref
+    "sphinx_gitref",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/configuration.rst

@@ -211,7 +211,7 @@ Multiple styles
 
 You can also use multiple styles and mix local files and URLs.
 
-Example of usage: the ``[tool.nitpick]`` table on `Nitpick's own pyproject.toml <https://github.com/andreoliwa/nitpick/blob/v0.31.0/pyproject.toml#L1-L7>`_.
+Example of usage: the ``[tool.nitpick]`` table on :gitref:`Nitpick's own pyproject.toml <pyproject.toml#L1-L7>`.
 
 .. code-block:: toml
 

docs/flake8_plugin.rst

@@ -43,7 +43,7 @@ Pre-commit hook and flake8
 
 Currently, the default pre-commit_ hook uses flake8_ in an `unconventional and not recommended way <https://github.com/pre-commit/pre-commit.com/pull/353#issuecomment-632224465>`_.
 
-`It calls flake8 directly <https://github.com/andreoliwa/nitpick/blob/develop/.pre-commit-hooks.yaml#L5>`_::
+:gitref:`It calls flake8 directly <.pre-commit-hooks.yaml#L5>`::
 
   flake8 --select=NIP
 
@@ -72,7 +72,7 @@ So basically the pre-commit hook would be useless to guarantee that your config
 
 .. note::
 
-  To avoid this, use the `other pre-commit hooks <https://github.com/andreoliwa/nitpick/blob/develop/.pre-commit-hooks.yaml#L10>`_, the ones that call the Nitpick CLI directly instead of running ``flake8``.
+  To avoid this, use the :gitref:`other pre-commit hooks <.pre-commit-hooks.yaml#L10>`, the ones that call the Nitpick CLI directly instead of running ``flake8``.
 
 Root dir of the project
 -----------------------

docs/library.rst

@@ -7,7 +7,7 @@ Library (Presets)
 
 If you want to :ref:`configure your own style <configure-your-own-style>`, those are the some styles you can reuse.
 
-Many TOML_ configs below are used in the `default style file`_.
+Many TOML_ configs below are used in the :gitref:`default style file <nitpick-style.toml>`.
 
 You can use these examples directly with their ``py://`` URL (see :ref:`multiple_styles`), or copy/paste the TOML into your own style file.
 
@@ -21,21 +21,21 @@ any
 
    * - Style URL
      - Description
-   * - `py://nitpick/resources/any/codeclimate <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/any/codeclimate.toml>`_
+   * - :gitref:`py://nitpick/resources/any/codeclimate <src/nitpick/resources/any/codeclimate.toml>`
      - `CodeClimate <https://codeclimate.com/>`_
-   * - `py://nitpick/resources/any/commitizen <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/any/commitizen.toml>`_
+   * - :gitref:`py://nitpick/resources/any/commitizen <src/nitpick/resources/any/commitizen.toml>`
      - `Commitizen (Python) <https://github.com/commitizen-tools/commitizen>`_
-   * - `py://nitpick/resources/any/commitlint <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/any/commitlint.toml>`_
+   * - :gitref:`py://nitpick/resources/any/commitlint <src/nitpick/resources/any/commitlint.toml>`
      - `commitlint <https://github.com/conventional-changelog/commitlint>`_
-   * - `py://nitpick/resources/any/editorconfig <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/any/editorconfig.toml>`_
+   * - :gitref:`py://nitpick/resources/any/editorconfig <src/nitpick/resources/any/editorconfig.toml>`
      - `EditorConfig <http://editorconfig.org/>`_
-   * - `py://nitpick/resources/any/git-legal <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/any/git-legal.toml>`_
+   * - :gitref:`py://nitpick/resources/any/git-legal <src/nitpick/resources/any/git-legal.toml>`
      - `Git.legal - CodeClimate Community Edition <https://github.com/kmewhort/git.legal-codeclimate>`_
-   * - `py://nitpick/resources/any/markdownlint <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/any/markdownlint.toml>`_
+   * - :gitref:`py://nitpick/resources/any/markdownlint <src/nitpick/resources/any/markdownlint.toml>`
      - `Markdown lint <https://github.com/markdownlint/markdownlint>`_
-   * - `py://nitpick/resources/any/pre-commit-hooks <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/any/pre-commit-hooks.toml>`_
+   * - :gitref:`py://nitpick/resources/any/pre-commit-hooks <src/nitpick/resources/any/pre-commit-hooks.toml>`
      - `pre-commit hooks for any project <https://github.com/pre-commit/pre-commit-hooks>`_
-   * - `py://nitpick/resources/any/prettier <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/any/prettier.toml>`_
+   * - :gitref:`py://nitpick/resources/any/prettier <src/nitpick/resources/any/prettier.toml>`
      - `Prettier <https://github.com/prettier/prettier>`_
 
 javascript
@@ -46,7 +46,7 @@ javascript
 
    * - Style URL
      - Description
-   * - `py://nitpick/resources/javascript/package-json <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/javascript/package-json.toml>`_
+   * - :gitref:`py://nitpick/resources/javascript/package-json <src/nitpick/resources/javascript/package-json.toml>`
      - `package.json <https://github.com/yarnpkg/website/blob/master/lang/en/docs/package-json.md>`_
 
 kotlin
@@ -57,7 +57,7 @@ kotlin
 
    * - Style URL
      - Description
-   * - `py://nitpick/resources/kotlin/ktlint <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/kotlin/ktlint.toml>`_
+   * - :gitref:`py://nitpick/resources/kotlin/ktlint <src/nitpick/resources/kotlin/ktlint.toml>`
      - `ktlint <https://github.com/pinterest/ktlint>`_
 
 presets
@@ -68,7 +68,7 @@ presets
 
    * - Style URL
      - Description
-   * - `py://nitpick/resources/presets/nitpick <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/presets/nitpick.toml>`_
+   * - :gitref:`py://nitpick/resources/presets/nitpick <src/nitpick/resources/presets/nitpick.toml>`
      - `Default style file for Nitpick <https://nitpick.rtfd.io/>`_
 
 proto
@@ -79,7 +79,7 @@ proto
 
    * - Style URL
      - Description
-   * - `py://nitpick/resources/proto/protolint <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/proto/protolint.toml>`_
+   * - :gitref:`py://nitpick/resources/proto/protolint <src/nitpick/resources/proto/protolint.toml>`
      - `protolint (Protobuf linter) <https://github.com/yoheimuta/protolint>`_
 
 python
@@ -90,49 +90,49 @@ python
 
    * - Style URL
      - Description
-   * - `py://nitpick/resources/python/310 <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/310.toml>`_
+   * - :gitref:`py://nitpick/resources/python/310 <src/nitpick/resources/python/310.toml>`
      - Python 3.10
-   * - `py://nitpick/resources/python/37 <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/37.toml>`_
+   * - :gitref:`py://nitpick/resources/python/37 <src/nitpick/resources/python/37.toml>`
      - Python 3.7
-   * - `py://nitpick/resources/python/38 <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/38.toml>`_
+   * - :gitref:`py://nitpick/resources/python/38 <src/nitpick/resources/python/38.toml>`
      - Python 3.8
-   * - `py://nitpick/resources/python/39 <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/39.toml>`_
+   * - :gitref:`py://nitpick/resources/python/39 <src/nitpick/resources/python/39.toml>`
      - Python 3.9
-   * - `py://nitpick/resources/python/absent <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/absent.toml>`_
+   * - :gitref:`py://nitpick/resources/python/absent <src/nitpick/resources/python/absent.toml>`
      - Files that should not exist
-   * - `py://nitpick/resources/python/autoflake <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/autoflake.toml>`_
+   * - :gitref:`py://nitpick/resources/python/autoflake <src/nitpick/resources/python/autoflake.toml>`
      - `autoflake <https://github.com/myint/autoflake>`_
-   * - `py://nitpick/resources/python/bandit <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/bandit.toml>`_
+   * - :gitref:`py://nitpick/resources/python/bandit <src/nitpick/resources/python/bandit.toml>`
      - `Bandit <https://github.com/PyCQA/bandit>`_
-   * - `py://nitpick/resources/python/black <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/black.toml>`_
+   * - :gitref:`py://nitpick/resources/python/black <src/nitpick/resources/python/black.toml>`
      - `Black <https://github.com/psf/black>`_
-   * - `py://nitpick/resources/python/flake8 <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/flake8.toml>`_
+   * - :gitref:`py://nitpick/resources/python/flake8 <src/nitpick/resources/python/flake8.toml>`
      - `Flake8 <https://github.com/PyCQA/flake8>`_
-   * - `py://nitpick/resources/python/github-workflow <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/github-workflow.toml>`_
+   * - :gitref:`py://nitpick/resources/python/github-workflow <src/nitpick/resources/python/github-workflow.toml>`
      - `GitHub Workflow for Python <https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions>`_
-   * - `py://nitpick/resources/python/ipython <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/ipython.toml>`_
+   * - :gitref:`py://nitpick/resources/python/ipython <src/nitpick/resources/python/ipython.toml>`
      - `IPython <https://github.com/ipython/ipython>`_
-   * - `py://nitpick/resources/python/isort <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/isort.toml>`_
+   * - :gitref:`py://nitpick/resources/python/isort <src/nitpick/resources/python/isort.toml>`
      - `isort <https://github.com/PyCQA/isort>`_
-   * - `py://nitpick/resources/python/mypy <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/mypy.toml>`_
+   * - :gitref:`py://nitpick/resources/python/mypy <src/nitpick/resources/python/mypy.toml>`
      - `Mypy <https://github.com/python/mypy>`_
-   * - `py://nitpick/resources/python/poetry-editable <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/poetry-editable.toml>`_
+   * - :gitref:`py://nitpick/resources/python/poetry-editable <src/nitpick/resources/python/poetry-editable.toml>`
      - `Poetry (editable projects; PEP 600 support) <https://github.com/python-poetry/poetry>`_
-   * - `py://nitpick/resources/python/poetry <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/poetry.toml>`_
+   * - :gitref:`py://nitpick/resources/python/poetry <src/nitpick/resources/python/poetry.toml>`
      - `Poetry <https://github.com/python-poetry/poetry>`_
-   * - `py://nitpick/resources/python/pre-commit-hooks <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/pre-commit-hooks.toml>`_
+   * - :gitref:`py://nitpick/resources/python/pre-commit-hooks <src/nitpick/resources/python/pre-commit-hooks.toml>`
      - `pre-commit hooks for Python projects <https://pre-commit.com/hooks>`_
-   * - `py://nitpick/resources/python/pylint <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/pylint.toml>`_
+   * - :gitref:`py://nitpick/resources/python/pylint <src/nitpick/resources/python/pylint.toml>`
      - `Pylint <https://github.com/PyCQA/pylint>`_
-   * - `py://nitpick/resources/python/radon <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/radon.toml>`_
+   * - :gitref:`py://nitpick/resources/python/radon <src/nitpick/resources/python/radon.toml>`
      - `Radon <https://github.com/rubik/radon>`_
-   * - `py://nitpick/resources/python/readthedocs <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/readthedocs.toml>`_
+   * - :gitref:`py://nitpick/resources/python/readthedocs <src/nitpick/resources/python/readthedocs.toml>`
      - `Read the Docs <https://github.com/readthedocs/readthedocs.org>`_
-   * - `py://nitpick/resources/python/sonar-python <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/sonar-python.toml>`_
+   * - :gitref:`py://nitpick/resources/python/sonar-python <src/nitpick/resources/python/sonar-python.toml>`
      - `SonarQube Python plugin <https://github.com/SonarSource/sonar-python>`_
-   * - `py://nitpick/resources/python/stable <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/stable.toml>`_
+   * - :gitref:`py://nitpick/resources/python/stable <src/nitpick/resources/python/stable.toml>`
      - Current stable Python version
-   * - `py://nitpick/resources/python/tox <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/tox.toml>`_
+   * - :gitref:`py://nitpick/resources/python/tox <src/nitpick/resources/python/tox.toml>`
      - `tox <https://github.com/tox-dev/tox>`_
 
 shell
@@ -143,9 +143,9 @@ shell
 
    * - Style URL
      - Description
-   * - `py://nitpick/resources/shell/bashate <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/shell/bashate.toml>`_
+   * - :gitref:`py://nitpick/resources/shell/bashate <src/nitpick/resources/shell/bashate.toml>`
      - `bashate (code style for Bash) <https://github.com/openstack/bashate>`_
-   * - `py://nitpick/resources/shell/shellcheck <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/shell/shellcheck.toml>`_
+   * - :gitref:`py://nitpick/resources/shell/shellcheck <src/nitpick/resources/shell/shellcheck.toml>`
      - `ShellCheck (static analysis for shell scripts) <https://github.com/koalaman/shellcheck>`_
-   * - `py://nitpick/resources/shell/shfmt <https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/shell/shfmt.toml>`_
+   * - :gitref:`py://nitpick/resources/shell/shfmt <src/nitpick/resources/shell/shfmt.toml>`
      - `shfmt (shell script formatter) <https://github.com/mvdan/sh>`_

docs/nitpick_section.rst

@@ -65,7 +65,7 @@ Multiple keys can be added.
 
 Styles can include other styles. Just provide a list of styles to include.
 
-Example of usage: `Nitpick's default style <https://github.com/andreoliwa/nitpick/blob/v0.31.0/nitpick-style.toml>`_.
+Example of usage: :gitref:`Nitpick's default style <nitpick-style.toml>`.
 
 .. code-block:: toml
 

docs/plugins.rst

@@ -1,10 +1,5 @@
 .. include:: targets.rst
 
-.. _flake8 configuration: https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/flake8.toml
-.. _the default config for package.json: https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/javascript/package-json.toml
-.. _the default pre-commit hooks: https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/any/pre-commit-hooks.toml
-.. _Python 3.8 version constraint: https://github.com/andreoliwa/nitpick/blob/v0.31.0/src/nitpick/resources/python/38.toml
-
 Plugins
 =======
 
@@ -31,7 +26,8 @@ Examples of ``.ini`` files handled by this plugin:
 - `tox.ini <https://github.com/tox-dev/tox>`_
 - `.pylintrc <https://pylint.readthedocs.io/en/latest/user_guide/run.html#command-line-options>`_
 
-Style examples enforcing values on INI files: `flake8 configuration`_.
+Style examples enforcing values on INI files: :gitref:`flake8 configuration
+<src/nitpick/resources/python/flake8.toml>`.
 
 .. _jsonplugin:
 
@@ -41,7 +37,7 @@ JSON files
 Enforce configurations and autofix JSON files.
 
 Add the configurations for the file name you wish to check.
-Style example: `the default config for package.json`_.
+Style example: :gitref:`the default config for package.json <src/nitpick/resources/javascript/package-json.toml>`.
 
 .. _textplugin:
 
@@ -72,7 +68,7 @@ E.g.: `pyproject.toml (PEP 518) <https://www.python.org/dev/peps/pep-0518/#file-
 See also `the [tool.poetry] section of the pyproject.toml file
 <https://github.com/python-poetry/poetry/blob/master/docs/pyproject.md>`_.
 
-Style example: `Python 3.8 version constraint`_.
+Style example: :gitref:`Python 3.8 version constraint <src/nitpick/resources/python/38.toml>`.
 There are :ref:`many other examples here <library>`.
 
 .. _yamlplugin:
@@ -83,7 +79,7 @@ YAML files
 Enforce configurations and autofix YAML files.
 
 - Example: `.pre-commit-config.yaml <https://pre-commit.com/#pre-commit-configyaml---top-level>`_.
-- Style example: `the default pre-commit hooks`_.
+- Style example: :gitref:`the default pre-commit hooks <src/nitpick/resources/any/pre-commit-hooks.toml>`.
 
 .. warning::
 

docs/quickstart.rst

@@ -48,7 +48,7 @@ Nitpick is also a flake8_ plugin, so you can run this on a project with at least
 
     flake8 .
 
-Nitpick_ will download and use the opinionated `default style file`_.
+Nitpick_ will download and use the opinionated :gitref:`default style file <nitpick-style.toml>`.
 
 You can use it as a template to :ref:`configure-your-own-style`.