docs: add tox to the examples, check links after other commands

docs/examples.rst

@@ -412,3 +412,41 @@ Contents of `styles/python39.toml <https://github.com/andreoliwa/nitpick/blob/v0
 
     ["pyproject.toml".tool.poetry.dependencies]
     python = "^3.9"
+
+.. _example-tox:
+
+tox_
+----
+
+Contents of `styles/tox.toml <https://github.com/andreoliwa/nitpick/blob/v0.24.1/styles/tox.toml>`_:
+
+.. code-block:: toml
+
+    ["tox.ini".tox]
+    # https://tox.readthedocs.io/en/latest/config.html
+    isolated_build = true
+
+    ["tox.ini".testenv]
+    description = "Run tests with pytest and coverage"
+    extras = "test"
+
+    ["tox.ini"."coverage:run"]
+    # https://coverage.readthedocs.io/en/latest/config.html#run
+    branch = true
+    parallel = true
+    source = "src/"
+    # TODO: deal with multiline INI values in https://github.com/andreoliwa/nitpick/issues/271
+    #omit = """tests/*
+    #.tox/*
+    #*/pypoetry/virtualenvs/*
+    #"""
+    # This config is needed by https://github.com/marketplace/actions/coveralls-python#usage
+    relative_files = true
+
+    ["tox.ini"."coverage:report"]
+    # https://coverage.readthedocs.io/en/latest/config.html#report
+    show_missing = true
+    precision = 2
+    skip_covered = true
+    skip_empty = true
+    sort = "Cover"

docs/generate_rst.py

@@ -46,6 +46,7 @@
         "python37.toml": "Python 3.7",
         "python38.toml": "Python 3.8",
         "python39.toml": "Python 3.9",
+        "tox.toml": "tox_",
     }
 )
 CLI_MAPPING = [

docs/plugins.rst

@@ -45,6 +45,7 @@ Examples of ``.ini`` files handled by this plugin:
 
 - `setup.cfg <https://docs.python.org/3/distutils/configfile.html>`_
 - `.editorconfig <https://editorconfig.org/>`_
+- `tox.ini <https://github.com/tox-dev/tox>`_
 
 Style examples enforcing values on INI files: :ref:`flake8 configuration <example-flake8>`.
 

docs/targets.rst

@@ -8,20 +8,21 @@
 .. _Bash: https://www.gnu.org/software/bash/
 .. _black: https://github.com/psf/black
 .. _commitlint: https://commitlint.js.org/
-.. _Django: https://www.djangoproject.com
+.. _Django: https://github.com/django/django
 .. _EditorConfig: https://editorconfig.org
-.. _flake8: https://gitlab.com/pycqa/flake8/
+.. _flake8: https://gitlab.com/pycqa/flake8
 .. _Flask CLI: https://flask.palletsprojects.com/en/1.1.x/cli/
 .. _Invoke: https://github.com/pyinvoke/invoke
-.. _IPython: https://ipython.org
-.. _isort: https://github.com/PyCQA/isort/
-.. _mypy: https://github.com/python/mypy/
-.. _Nitpick: https://github.com/andreoliwa/nitpick/
+.. _IPython: https://github.com/ipython/ipython
+.. _isort: https://github.com/PyCQA/isort
+.. _mypy: https://github.com/python/mypy
+.. _Nitpick: https://github.com/andreoliwa/nitpick
 .. _package.json: https://docs.npmjs.com/files/package.json
-.. _Pipenv: https://github.com/pypa/pipenv/
+.. _Pipenv: https://github.com/pypa/pipenv
 .. _pipx: https://github.com/pipxproject/pipx
-.. _Poetry: https://github.com/python-poetry/poetry/
-.. _pre-commit: https://pre-commit.com/
-.. _Pylint: https://www.pylint.org
-.. _pytest: https://pytest.org/
+.. _Poetry: https://github.com/python-poetry/poetry
+.. _pre-commit: https://github.com/pre-commit/pre-commit
+.. _Pylint: https://github.com/PyCQA/pylint
+.. _pytest: https://github.com/pytest-dev/pytest
 .. _TOML: https://github.com/toml-lang/toml
+.. _tox: https://github.com/tox-dev/tox

src/nitpick/plugins/ini.py

@@ -37,7 +37,7 @@ class IniPlugin(NitpickPlugin):
 
     - `setup.cfg <https://docs.python.org/3/distutils/configfile.html>`_
     - `.editorconfig <https://editorconfig.org/>`_
-    - `tox.ini <https://tox.readthedocs.io/en/latest/>`_
+    - `tox.ini <https://github.com/tox-dev/tox>`_
 
     Style examples enforcing values on INI files: :ref:`flake8 configuration <example-flake8>`.
     """

tasks.py

@@ -155,12 +155,13 @@ def doc(c, full=False, recreate=False, links=False, open=False, debug=False):
     c.run(f"poetry run {tox.api}")
     if debug:
         c.run("poetry run sphinx-apidoc --help")
-    if links:
-        c.run(f"poetry run {tox.check_links}", warn=True)
 
     debug_options = "-nWT --keep-going -vvv" if debug else ""
     c.run(f"poetry run {tox.html_docs} {debug_options}")
 
+    if links:
+        c.run(f"poetry run {tox.check_links}", warn=True)
+
     if open:
         c.run(f"open {DOCS_BUILD_PATH}/docs_out/index.html")
 

tox.ini

@@ -69,13 +69,16 @@ extras = doc
 commands =
     python3 docs/generate_rst.py
     sphinx-apidoc --force --follow-links --module-first --separate --implicit-namespaces --ext-autodoc --ext-doctest --ext-intersphinx --ext-todo --ext-coverage --ext-imgmath --ext-mathjax --ext-ifconfig --ext-viewcode --ext-githubpages --output-dir docs/source src/nitpick/
+
+    # Use these options to debug Sphinx: -nWT --keep-going -vvv
+    sphinx-build --color -j auto -d "{toxworkdir}/docs_doctree" -b html docs "{toxworkdir}/docs_out" {posargs}
+
+    # Run link checks after building the docs
     # To stop failing when a page is unreachable, add a hyphen at the start of the line:
     # https://tox.readthedocs.io/en/latest/example/basic.html#ignoring-exit-code
     # Some errors during link check have to be ignored.
     # E.g.: when a new TOML style is added, its link will be broken until a new release is published.
     - sphinx-build --color -j auto -b linkcheck docs "{toxworkdir}/docs_out"
-    # Use these options to debug Sphinx: -nWT --keep-going -vvv
-    sphinx-build --color -j auto -d "{toxworkdir}/docs_doctree" -b html docs "{toxworkdir}/docs_out" {posargs}
 
 [pytest]
 # https://docs.pytest.org/en/stable/customize.html#tox-ini