diff options
| -rw-r--r-- | .github/workflows/lint.yml | 4 | ||||
| -rw-r--r-- | Makefile | 2 | ||||
| -rw-r--r-- | doc/development/index.rst | 6 | ||||
| -rw-r--r-- | doc/development/tutorials/autodoc_ext.rst | 4 | ||||
| -rw-r--r-- | doc/extdev/deprecated.rst | 2 | ||||
| -rw-r--r-- | doc/latex.rst | 6 | ||||
| -rw-r--r-- | doc/templating.rst | 2 | ||||
| -rw-r--r-- | doc/tutorial/describing-code.rst | 9 | ||||
| -rw-r--r-- | doc/usage/extensions/intersphinx.rst | 2 | ||||
| -rw-r--r-- | doc/usage/extensions/napoleon.rst | 4 | ||||
| -rw-r--r-- | doc/usage/installation.rst | 2 | ||||
| -rw-r--r-- | setup.py | 1 | ||||
| -rw-r--r-- | tox.ini | 4 | ||||
| -rw-r--r-- | utils/doclinter.py | 77 |
14 files changed, 24 insertions, 101 deletions
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 913abcedd..e33ffc2d3 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@v4 with: - python-version: 3.6 + python-version: '>=3.7' - name: Install dependencies run: pip install -U tox - name: Run Tox @@ -62,7 +62,7 @@ type-check: .PHONY: doclinter doclinter: - python utils/doclinter.py CHANGES *.rst doc/ + sphinx-lint --enable line-too-long --max-line-length 85 CHANGES *.rst doc/ .PHONY: test test: diff --git a/doc/development/index.rst b/doc/development/index.rst index b4a7920ba..8ae71e76f 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 d8905710c..8de2e4d4a 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 98bd463a9..81167cd4d 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 b49714e88..294de5599 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 d9755a836..f2f4022ad 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/tutorial/describing-code.rst b/doc/tutorial/describing-code.rst index 57f1b2008..24fea38a6 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/doc/usage/extensions/intersphinx.rst b/doc/usage/extensions/intersphinx.rst index 6b7b1e1bd..a70c7c531 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 ad5af65c6..e1f90b562 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 b85a6cd2a..3e7745a27 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 <https://chocolatey.org/install>`_ before running this. @@ -42,6 +42,7 @@ extras_require = { 'flake8>=3.5.0', 'isort', 'mypy>=0.950', + 'sphinx-lint', 'docutils-stubs', "types-typed-ast", "types-requests", @@ -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 --disable missing-space-after-literal --enable line-too-long --max-line-length 85 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 d67a49b05..000000000 --- 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:])) |