From 0d141a8da7d7558dbf749fcd9731621e0a72f029 Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Mon, 25 Apr 2022 23:13:18 +0200 Subject: [PATCH 1/5] Passing sphinx-lint on sphinx doc. --- doc/development/index.rst | 6 +++--- doc/development/tutorials/autodoc_ext.rst | 4 +--- doc/extdev/deprecated.rst | 2 +- doc/latex.rst | 6 +++--- doc/templating.rst | 2 +- doc/usage/extensions/intersphinx.rst | 2 +- doc/usage/extensions/napoleon.rst | 4 ++-- doc/usage/installation.rst | 2 +- 8 files changed, 13 insertions(+), 15 deletions(-) diff --git a/doc/development/index.rst b/doc/development/index.rst index b4a7920ba03..8ae71e76f73 100644 --- a/doc/development/index.rst +++ b/doc/development/index.rst @@ -2,10 +2,10 @@ Extending Sphinx ================ -This guide is aimed at giving a quick introduction for those wishing to -develop their own extensions for Sphinx. Sphinx possesses significant +This guide is aimed at giving a quick introduction for those wishing to +develop their own extensions for Sphinx. Sphinx possesses significant extensibility capabilities including the ability to hook into almost every -point of the build process. If you simply wish to use Sphinx with existing +point of the build process. If you simply wish to use Sphinx with existing extensions, refer to :doc:`/usage/index`. For a more detailed discussion of the extension interface see :doc:`/extdev/index`. diff --git a/doc/development/tutorials/autodoc_ext.rst b/doc/development/tutorials/autodoc_ext.rst index d8905710c66..8de2e4d4a84 100644 --- a/doc/development/tutorials/autodoc_ext.rst +++ b/doc/development/tutorials/autodoc_ext.rst @@ -123,7 +123,7 @@ For example, you have the following ``IntEnum``: .. code-block:: python :caption: my_enums.py - + class Colors(IntEnum): """Colors enumerator""" NONE = 0 @@ -138,5 +138,3 @@ This will be the documentation file with auto-documentation directive: :caption: index.rst .. autointenum:: my_enums.Colors - - diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst index 98bd463a95c..81167cd4ddd 100644 --- a/doc/extdev/deprecated.rst +++ b/doc/extdev/deprecated.rst @@ -824,7 +824,7 @@ The following is a list of deprecated interfaces. - ``sphinx.domains.std.StandardDomain.process_doc()`` * - ``sphinx.domains.js.JSObject.display_prefix`` - - + - - 4.3 - ``sphinx.domains.js.JSObject.get_display_prefix()`` diff --git a/doc/latex.rst b/doc/latex.rst index b49714e88a4..294de559907 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -330,7 +330,7 @@ Keys that don't need to be overridden unless in special cases are: .. attention:: - - Do not use this key for a :confval:`latex_engine` other than + - Do not use this key for a :confval:`latex_engine` other than ``'pdflatex'``. - If Greek is main language, do not use this key. Since Sphinx 2.2.1, @@ -528,7 +528,7 @@ Keys that don't need to be overridden unless in special cases are: is adapted to the relative widths of the FreeFont family. .. versionchanged:: 4.0.0 - Changed default for ``'pdflatex'``. Previously it was using + Changed default for ``'pdflatex'``. Previously it was using ``'\\fvset{fontsize=\\small}'``. .. versionchanged:: 4.1.0 @@ -915,7 +915,7 @@ Do not use quotes to enclose values, whether numerical or strings. ``attentionBorderColor``, ``dangerBorderColor``, ``errorBorderColor`` -.. |wgbdcolorslatex| replace:: ``warningBorderColor``, and +.. |wgbdcolorslatex| replace:: ``warningBorderColor``, and ``(caution|attention|danger|error)BorderColor`` .. else latex goes into right margin, as it does not hyphenate the names diff --git a/doc/templating.rst b/doc/templating.rst index 3d80edd6009..0d143208ce0 100644 --- a/doc/templating.rst +++ b/doc/templating.rst @@ -377,7 +377,7 @@ in the future. .. data:: sphinx_version_tuple The version of Sphinx used to build represented as a tuple of five elements. - For Sphinx version 3.5.1 beta 3 this would be `(3, 5, 1, 'beta', 3)``. + For Sphinx version 3.5.1 beta 3 this would be ``(3, 5, 1, 'beta', 3)``. The fourth element can be one of: ``alpha``, ``beta``, ``rc``, ``final``. ``final`` always has 0 as the last element. diff --git a/doc/usage/extensions/intersphinx.rst b/doc/usage/extensions/intersphinx.rst index 6b7b1e1bd85..a70c7c531a1 100644 --- a/doc/usage/extensions/intersphinx.rst +++ b/doc/usage/extensions/intersphinx.rst @@ -209,7 +209,7 @@ The Intersphinx extension provides the following role. If you would like to constrain the lookup to a specific external project, then the key of the project, as specified in :confval:`intersphinx_mapping`, - is added as well to get the two forms + is added as well to get the two forms - ``:external+invname:domain:reftype:`target```, e.g., ``:external+python:py:class:`zipfile.ZipFile```, or diff --git a/doc/usage/extensions/napoleon.rst b/doc/usage/extensions/napoleon.rst index ad5af65c67c..e1f90b562c4 100644 --- a/doc/usage/extensions/napoleon.rst +++ b/doc/usage/extensions/napoleon.rst @@ -221,7 +221,7 @@ Google style with Python 3 type annotations:: """ return True - + class Class: """Summary line. @@ -251,7 +251,7 @@ Google style with types in docstrings:: """ return True - + class Class: """Summary line. diff --git a/doc/usage/installation.rst b/doc/usage/installation.rst index b85a6cd2adf..3e7745a27e0 100644 --- a/doc/usage/installation.rst +++ b/doc/usage/installation.rst @@ -118,7 +118,7 @@ Chocolatey :: $ choco install sphinx - + You would need to `install Chocolatey `_ before running this. From cf15288d6dd4fa28c5e64bb643ccc35932ab24cf Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Tue, 26 Apr 2022 23:43:42 +0200 Subject: [PATCH 2/5] Use sphinx-lint in Makefile, tox (and github actions) checks. --- .github/workflows/lint.yml | 4 +- Makefile | 2 +- setup.py | 1 + tox.ini | 4 +- utils/doclinter.py | 77 -------------------------------------- 5 files changed, 6 insertions(+), 82 deletions(-) delete mode 100644 utils/doclinter.py diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 913abcedd53..2f0c5de7c90 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -13,9 +13,9 @@ jobs: steps: - uses: actions/checkout@v2 - name: Set up Python - uses: actions/setup-python@v1 + uses: actions/setup-python@v3 with: - python-version: 3.6 + python-version: '>=3.7' - name: Install dependencies run: pip install -U tox - name: Run Tox diff --git a/Makefile b/Makefile index b430bdd1b2b..3b1ecda32f5 100644 --- a/Makefile +++ b/Makefile @@ -62,7 +62,7 @@ type-check: .PHONY: doclinter doclinter: - python utils/doclinter.py CHANGES *.rst doc/ + sphinx-lint CHANGES *.rst doc/ .PHONY: test test: diff --git a/setup.py b/setup.py index 4ec21569713..b49f3d07c83 100644 --- a/setup.py +++ b/setup.py @@ -42,6 +42,7 @@ 'flake8>=3.5.0', 'isort', 'mypy>=0.950', + 'sphinx-lint', 'docutils-stubs', "types-typed-ast", "types-requests", diff --git a/tox.ini b/tox.ini index 105a02597ec..73b67b15d2e 100644 --- a/tox.ini +++ b/tox.ini @@ -81,9 +81,9 @@ basepython = python3 description = Lint documentation. extras = - docs + lint commands = - python utils/doclinter.py CHANGES CONTRIBUTING.rst README.rst doc/ + sphinx-lint CHANGES CONTRIBUTING.rst README.rst doc/ [testenv:twine] basepython = python3 diff --git a/utils/doclinter.py b/utils/doclinter.py deleted file mode 100644 index d67a49b0510..00000000000 --- a/utils/doclinter.py +++ /dev/null @@ -1,77 +0,0 @@ -"""A linter for Sphinx docs""" - -import os -import re -import sys -from typing import List - -MAX_LINE_LENGTH = 85 -LONG_INTERPRETED_TEXT = re.compile(r'^\s*\W*(:(\w+:)+)?`.*`\W*$') -CODE_BLOCK_DIRECTIVE = re.compile(r'^(\s*)\.\. code-block::') -LEADING_SPACES = re.compile(r'^(\s*)') - - -def lint(path: str) -> int: - with open(path, encoding='utf-8') as f: - document = f.readlines() - - errors = 0 - in_code_block = False - code_block_depth = 0 - for i, line in enumerate(document): - if line.endswith(' '): - print('%s:%d: the line ends with whitespace.' % - (path, i + 1)) - errors += 1 - - matched = CODE_BLOCK_DIRECTIVE.match(line) - if matched: - in_code_block = True - code_block_depth = len(matched.group(1)) - elif in_code_block: - if line.strip() == '': - pass - else: - spaces = LEADING_SPACES.match(line).group(1) - if len(spaces) <= code_block_depth: - in_code_block = False - elif LONG_INTERPRETED_TEXT.match(line): - pass - elif len(line) > MAX_LINE_LENGTH: - if re.match(r'^\s*\.\. ', line): - # ignore directives and hyperlink targets - pass - elif re.match(r'^\s*__ ', line): - # ignore anonymous hyperlink targets - pass - elif re.match(r'^\s*``[^`]+``$', line): - # ignore a very long literal string - pass - else: - print('%s:%d: the line is too long (%d > %d).' % - (path, i + 1, len(line), MAX_LINE_LENGTH)) - errors += 1 - - return errors - - -def main(args: List[str]) -> int: - errors = 0 - for path in args: - if os.path.isfile(path): - errors += lint(path) - elif os.path.isdir(path): - for root, _dirs, files in os.walk(path): - for filename in files: - if filename.endswith('.rst'): - path = os.path.join(root, filename) - errors += lint(path) - - if errors: - return 1 - else: - return 0 - - -if __name__ == '__main__': - sys.exit(main(sys.argv[1:])) From 638f6edb32c7a4ea080e8eb9b653edaac6a31f71 Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Mon, 23 May 2022 14:13:20 +0200 Subject: [PATCH 3/5] sphinx-lint: Enable line-too-long checker. --- Makefile | 2 +- doc/tutorial/describing-code.rst | 9 +++++---- tox.ini | 2 +- 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/Makefile b/Makefile index 3b1ecda32f5..9213820b70b 100644 --- a/Makefile +++ b/Makefile @@ -62,7 +62,7 @@ type-check: .PHONY: doclinter doclinter: - sphinx-lint CHANGES *.rst doc/ + sphinx-lint --enable line-too-long --max-line-length 85 CHANGES *.rst doc/ .PHONY: test test: diff --git a/doc/tutorial/describing-code.rst b/doc/tutorial/describing-code.rst index 57f1b200839..24fea38a6b7 100644 --- a/doc/tutorial/describing-code.rst +++ b/doc/tutorial/describing-code.rst @@ -85,10 +85,11 @@ you can use :rst:role:`py:func` for that, as follows: or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients` will raise an exception. -When generating code documentation, Sphinx will generate a cross-reference automatically just -by using the name of the object, without you having to explicitly use a role -for that. For example, you can describe the custom exception raised by the -function using the :rst:dir:`py:exception` directive: +When generating code documentation, Sphinx will generate a +cross-reference automatically just by using the name of the object, +without you having to explicitly use a role for that. For example, you +can describe the custom exception raised by the function using the +:rst:dir:`py:exception` directive: .. code-block:: rst :caption: docs/source/usage.rst diff --git a/tox.ini b/tox.ini index 73b67b15d2e..e4b2dd70cf5 100644 --- a/tox.ini +++ b/tox.ini @@ -83,7 +83,7 @@ description = extras = lint commands = - sphinx-lint CHANGES CONTRIBUTING.rst README.rst doc/ + sphinx-lint --enable line-too-long --max-line-length 85 CHANGES CONTRIBUTING.rst README.rst doc/ [testenv:twine] basepython = python3 From c57c3f7cd68958168fbc31af471b5d41811d1f3b Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Thu, 16 Jun 2022 19:14:03 +0100 Subject: [PATCH 4/5] Use setup-python v4 --- .github/workflows/lint.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 2f0c5de7c90..e33ffc2d329 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -13,7 +13,7 @@ jobs: steps: - uses: actions/checkout@v2 - name: Set up Python - uses: actions/setup-python@v3 + uses: actions/setup-python@v4 with: python-version: '>=3.7' - name: Install dependencies From c4a7b84e4e86cdee9eb3c65cea1e7c9d2baad952 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Thu, 16 Jun 2022 19:26:44 +0100 Subject: [PATCH 5/5] Disable ` missing-space-after-literal` --- tox.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index e4b2dd70cf5..99ea3f9dcdd 100644 --- a/tox.ini +++ b/tox.ini @@ -83,7 +83,7 @@ description = extras = lint commands = - sphinx-lint --enable line-too-long --max-line-length 85 CHANGES CONTRIBUTING.rst README.rst doc/ + sphinx-lint --disable missing-space-after-literal --enable line-too-long --max-line-length 85 CHANGES CONTRIBUTING.rst README.rst doc/ [testenv:twine] basepython = python3