pycqa / doc8 Goto Github PK
View Code? Open in Web Editor NEWStyle checker for sphinx (or other) rst documentation.
Home Page: https://github.com/PyCQA/doc8
License: Apache License 2.0
Style checker for sphinx (or other) rst documentation.
Home Page: https://github.com/PyCQA/doc8
License: Apache License 2.0
I often have very long tables that cannot be shortened and raise line-too-long doc8 errors. For example:
======================= ======================================================================================================
Header Description
======================= ======================================================================================================
Rather long header item My very extremely long-winded wordy verbose descriptive supercalifragilisticexpialidocious description
======================= ======================================================================================================
doc8 has an --allow-long-titles
option to prevent line-too-long errors for verbose titles. Could you also add an option to ignore line-too-long errors for very long tables?
doc8 currently requires docutils >=0.19
which is the latest version that exists at the moment. Is this really a hard requirement or was it set by accident within PR-103?
I do not know if it is reasonable to require e.g. >=0.18.1
instead.
Background: The trouble is that many different modules require specific docutils versions. doc8 is extremely strict in requiring the latest one, which is not yet supported by all the other modules.
Per pypa/pip#11120, including pip in pyproject.toml [build-system] requires causes failures when trying to install doc8.
I've been experiencing this issue as described catalyst-cooperative/pudl#1742 (comment), when pre-commit is trying to install the virtual environment that includes doc8.
I think that if pip were removed from your toml file, it would likely solve this issue.
Please do not use chardet to detect document encoding. For UTF-8 texts it works more or less reliably only for Latin-1 and Latin-1 Supplement unicode blocks, for Latin Extended-A and Extended-B it fails in about 50% cases wrongly detecting Windows encodings, eg. for UTF-8 document with Latin Extended-A content:
$ chardet docs/index.rst
docs/index.rst: Windows-1252 with confidence 0.594336283186
$ file docs/index.rst
docs/index.rst: UTF-8 Unicode text
In fact chardet reports low confidence in this case.
Example (taken from the Sphinx docs) to reproduce the error:
.. math::
:nowrap:
\begin{eqnarray}
y & = & ax^2 + bx + c \\
f(x) & = & x^2 + 2xy + y^2
\end{eqnarray}
Appears to be related to #26.
I just added doc8
to my pre-commit configuration (using the most recent hash a4740d8 as the version), and when committing a change to my README.rst
I got the following failure:
doc8.....................................................................Failed
hookid: doc8
Traceback (most recent call last):
File "/home/zane/miniconda3/envs/pudl/lib/python3.7/runpy.py", line 193, in _run_module_as_main
"__main__", mod_spec)
File "/home/zane/miniconda3/envs/pudl/lib/python3.7/runpy.py", line 85, in _run_code
exec(code, run_globals)
File "/home/zane/.cache/pre-commit/repomemqz1cs/py_env-python3.7/lib/python3.7/site-packages/doc8/__main__.py", line 20, in <module>
sys.exit(main())
TypeError: 'module' object is not callable
I ran pre-commit clean
and then attempted the commit again, and got the same error. However, when I run doc8
against the same file on the command line, it succeeds. Maybe there's something wonky with the script entrypoint arrangement?
From my .pre-commit-config.yml
file:
# Check for errors in reST files under the doc hierarchy
- repo: https://github.com/PyCQA/doc8
rev: a4740d8f4f41ce4e1e1d1b7dedc8f928f365b862
hooks:
- id: doc8
I thought the problem might be a mismatch between the installed v0.8.0 of doc8
and the most recent commit to master, so did pip install git+https://github.com/PyCQA/doc8.git
in my conda environment, which gave me v0.8.1.dev19, but I got the exact same behavior. doc8 --version
now gives 0.8.1 and when I do conda list | grep doc8
I get 0.8.1.dev19
so I think it really is using the version from the repository.
I tried to use doc8 as a pre-commit hook but the checks that passed on my Mac were failing in Github CI.
I even logged into the remote system using tunshell to debug and if I set the --max-line-length to something high like 120 it passes on the Github CI linux machine. So my only conclusion is that somehow the way doc8 on ubuntu was interpreting the .rst files and their line breaks was somehow different to MacOS?
setup.cfg
[doc8]
max-line-length=88
.pre-commit-config.yaml
- repo: https://github.com/PyCQA/doc8
rev: 0.8.1
hooks:
- id: doc8
args: ["--max-line-length=88", "--config=setup.cfg", "docs"]
The file installing.rst claims to be LF like all our .rst files.
I tried multiple different versions of the pre-commit hook, including the stable 0.8.1 and even just running the local pip installed doc8 0.8.1 with either the setup.cfg max line length or the direct CLI flag, or both.
https://github.com/OpenMined/PySyft/runs/1126002765?check_suite_focus=true
Here is an example file that fails on CI:
https://github.com/OpenMined/PySyft/pull/4564/files#diff-ba34ab03bbb1d37909716574e6134def
For now I have simply removed the doc8 checks again and force pushed.
Perhaps I am simply mis-understanding something here about the line breaks and doc8 on mac vs ubuntu?
I wanted to ask if this idea might be considered in scope for doc8: Parsing Python source code (*.py
), extracting the docstrings, and validating those as RST.
i.e. Something equivalent to the functionality my plugin https://github.com/peterjc/flake8-rst-docstrings brings to flake8. Internally this takes the AST of a Python file, and passes the docstrings to docutils
for validation via restructuredtext_lint
.
Sphinx redefines the pep
role to allow for an anchor: https://github.com/sphinx-doc/sphinx/blob/cc314f13e8a98393ab018d83d8957a724a6f338a/sphinx/roles.py#L198
Therefore :pep:`8#specification`
should be considered valid unless doc8 is called with --no-sphinx
. This is however not the case. Running doc8
on the above RST snippet results in the false positive “D000 PEP number must be a number from 0 to 9999”
I have a number of reusable GitHub CI wokflows. One of them creates python environments of different versions and runs checks and tests.
The doc8 command is common for any environment: doc8 --config pyproject.toml ./docs
Here you can see 3 different jobs with 3.9, 3.10 and 3.11 (in the middle) environments:
All the jobs, except 3.11 passed.
Pyproject.toml has the following simple setting:
[tool.doc8] # RST linter
# https://github.com/PyCQA/doc8
max-line-length = 99
The length of each string is lower than 99.
I tried run doc8 locally on Python 3.11.4 by doc8 --config pyproject.toml ./docs
and it also failed:
(py3.11) serge@dell:~/my_prj$ doc8 --config pyproject.toml docs/
Scanning...
Validating...
docs/index.rst:4: D001 Line too long
docs/index.rst:6: D001 Line too long
docs/index.rst:13: D001 Line too long
docs/index.rst:16: D001 Line too long
docs/index.rst:18: D001 Line too long
========
Total files scanned = 9
Total files ignored = 0
Total accumulated errors = 5
Detailed error counts:
- doc8.checks.CheckCarriageReturn = 0
- doc8.checks.CheckIndentationNoTab = 0
- doc8.checks.CheckMaxLineLength = 5
- doc8.checks.CheckNewlineEndOfFile = 0
- doc8.checks.CheckTrailingWhitespace = 0
- doc8.checks.CheckValidity = 0
So I have an error Error in "code-block" directive: unknown option: "linenos".
but it has been reported in #30 and resolved in #51, but it hasn't been released yet so I would need to install the github repo. It would be easier to release a new version on PyPI because 0.8.1 doesn't have the fix implemented.
doc8 triggers an error in Sphinx mode:
file:114: D000 Error in "math" directive:
unknown option: "label".
for the code which is legal for Sphinx:
.. math::
:label: somelabel
O = M_{CC} \times I+V_{CC},
Related to #26
docs/index.rst:2: D000 Error in "code-block" directive:
unknown option: "linenos".
The same for these options:
linenos
lineno-start
caption
emphasize-lines
dedent
In Sphinx, this is valid, but doc8 sees it as an error.
.. code-block:: python
:linenos:
:caption: test.py
:name: test.py
:emphasize-lines: 2
def foo():
return "bar"
We have a piece of documentation that looks like this:
Set region in platforms.yaml
.. code-block:: yaml
:emphasize-lines: 3
azurecloud:
enabled: true
region: West US 2
vm_size: Standard_DS1_v2
which is using the Sphinx emphasize-lines options to code-block
. This raises an error:
doc/rtd/topics/tests.rst:467: D000 Error in "code-block" directive:
unknown option: "emphasize-lines".
In Sphinx mode, I believe this should just be ignored.
doc8 fails when using .. code-block:: none
, which in Sphinx is the documented way to turn off syntax highlighting.
doc8 currently reports the error:
D000 Cannot analyze code. No Pygments lexer found for "none".
From the Sphinx documentation:
- none (no highlighting)
- default (similar to python3 but with a fallback to none without warning highlighting fails; the default when highlight_language isn’t set)
It looks like the current workaround, is to avoid the "none" option, and instead use the default (.. code-block::
) which is similar, but different. Alternatively, it is to find the appropriate lexer and enable highlighting, as I found in this commit working around this issue.
I can understand if it is determined not to support none
to avoid complexity, but even if that is the decision, it still seems like the decision would be worth capturing for those searching for this.
Thank you!
I don't want to check .rst
or .txt
files, only .bar
files.
Given:
$ ls
foo.bar foo.baz foo.rst foo.txt
running doc8
gives:
$ doc8 -v -e .bar .
Scanning...
Selecting './foo.bar'
Selecting './foo.txt'
Selecting './foo.rst'
---8<---
The same behavior occurs when using a config file. In my case, pyproject.toml
. This was suprising as one would expect that setting an option would override that option's defaults.
Obviously one could work around this using shell expansion (doc8 **/*.rst
), and thats ok for command line use. But, my ultimate goal is to control doc8
via config file like I do with other tooling, and doing:
[tool.doc8]
ignore-path = [
"*.txt",
"*/*.txt",
"*/*/*.txt",
"*/*/*/*.txt",
"*/*/*/*/*.txt",
"*/*/*/*/*/*.txt",
]
is just inelegant.
Travis is not enabled on PyCQA/doc8
and I do not have enough permissions to do it myself, please help with this as this is No1 priority before doing any other work.
When invoking doc8 if no --extension
value is provided in the command line argument, doc8 uses the defaults of ['.rst', '.txt']
for this value, if the --extension
command line argument is specified, its values are added to the defaults. When later it loads the configuration values from a pyproject.toml
file in the tool.doc8.extension
value, it will also extend the extensions with the values defined here.
Consider the following pyproject.toml
:
[tool.doc8]
extension = [".rst", ".py"]
And the following call to doc8:
doc8 .
This will result in doc8 using [".rst", ".txt", ".rst", ".py"]
instead of just the values in the pyproject.toml
file [".rst", ".py"]
.
The following call:
doc8 . --extension '.bin'
Will result in [".rst", ".txt", ".bin", ".rst", ".py"]
being used.
This behaviour is caused because of the append
store action in the --extension
parameter of argparse
in main.py
file, which appends to the default values specified for that parameter rather than replacing them, see issue https://bugs.python.org/issue16399.
In summary, there is no way to get rid of the default values for the extensions, [".rst", ".txt"]
will be included no matter how you invoke doc8 or what configuration you provide.
Is this the intended behaviour?
Hello,
for the Arch Linux environment, I would like to create a PKGBUILD for making a package instead of installing doc8 by pip. Among the source files I could not see a setup.py
that could be great to have for making easily the creation of a PKGBUILD.
Could you please submit a setup.py
file in order to install the module instead of using pip?
Hi, still having this problem.
It should be nice import all issues reported here: https://bugs.launchpad.net/doc8/+bug/1756704
Check the versions in pip_list.txt
The workflow failed to run: https://github.com/PyCQA/doc8/actions/runs/3748087258
Recent change in version 1.0.0 produces the following error:
Line 60 in 99dca1d
Traceback (most recent call last):
File "/opt/hostedtoolcache/Python/3.7.13/x64/bin/doc8", line 8, in <module>
sys.exit(main())
File "/opt/hostedtoolcache/Python/3.7.13/x64/lib/python3.7/site-packages/doc8/main.py", line 528, in main
result = doc8(args)
File "/opt/hostedtoolcache/Python/3.7.13/x64/lib/python3.7/site-packages/doc8/main.py", line 403, in doc8
error_counts = validate(args, files, result=result)
File "/opt/hostedtoolcache/Python/3.7.13/x64/lib/python3.7/site-packages/doc8/main.py", line 271, in validate
for line_num, code, message in c.report_iter(f):
File "/opt/hostedtoolcache/Python/3.7.13/x64/lib/python3.7/site-packages/doc8/checks.py", line 313, in report_iter
for issue in checker_func(parsed_file):
File "/opt/hostedtoolcache/Python/3.7.13/x64/lib/python3.7/site-packages/doc8/checks.py", line 252, in _rst_checker
nodes_lines, first_line = self._extract_node_lines(doc)
File "/opt/hostedtoolcache/Python/3.7.13/x64/lib/python3.7/site-packages/doc8/checks.py", line 182, in _extract_node_lines
for n in utils.filtered_traverse(doc, filter_systems):
File "/opt/hostedtoolcache/Python/3.7.13/x64/lib/python3.7/site-packages/doc8/utils.py", line 60, in filtered_traverse
for n in document.findall(include_self=True):
AttributeError: 'document' object has no attribute 'findall'
Include directives like this are valid Sphinx:
.. include:: /somefile.hrst
This is mentioned by the Sphinx developer here. The doc8 linter complains about the above definition though:
docs/source/myfile.rst:1: D000 Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: '/somefile.hrst'.
Sphinx includes the file just fine.
It would be useful to include some additional documentation about how to structure the config file when using pyproject.toml
.
I ran into some problems setting up the config file to ignore errors related to #78.
It looks like a pyproject.toml
that includes something like what I've posted below, will work:
[tool.doc8]
max-line-length = 88
ignore = ["D004"]
However, based on the existing README, I initially didn't have the error quoted or in brackets. Not quoting the error codes leads to errors when reading the pyproject.toml
file and leaving out the brackets from the ignore also appeared to make it so that doc8
didn't recognize what was being passed.
Can you confirm the above should work as expected to ignore error code D004? If so, should be an easy addition to the README to clarify for others.
I get false positive
D004 Found literal carriage return
at every line on Windows. It has been reported here first:
https://bugs.launchpad.net/doc8/+bug/1756704
Given a conf.py
containing:
project = "foo"
copyright = "2022, Julian Berman"
author = "Julian Berman"
rst_prolog = """
.. _example: https://example.com
"""
with an example
link defined in the rst_prolog, and a simple index.rst
using the target:
Foo
===
This is an `example`_.
doc8
emits:
~/Desktop/foo/docs is a git repository on main
⊙ doc8 . julian@Airm ●
Scanning...
Validating...
./index.rst:4: D000 Unknown target name: "example".
/Users/julian/.dotfiles/.local/share/virtualenvs/doc8/lib/python3.10/site-packages/doc8/parser.py:69: DeprecationWarning: The frontend.OptionParser class will be replaced by a subclass of argparse.ArgumentParser in Docutils 0.21 or later.
opt = frontend.OptionParser(components=[parser], defaults=defaults)
/opt/homebrew/Cellar/[email protected]/3.10.9/Frameworks/Python.framework/Versions/3.10/lib/python3.10/optparse.py:1000: DeprecationWarning: The frontend.Option class will be removed in Docutils 0.21 or later.
option = self.option_class(*args, **kwargs)
========
Total files scanned = 1
Total files ignored = 0
Total accumulated errors = 1
Detailed error counts:
- doc8.checks.CheckCarriageReturn = 0
- doc8.checks.CheckIndentationNoTab = 0
- doc8.checks.CheckMaxLineLength = 0
- doc8.checks.CheckNewlineEndOfFile = 0
- doc8.checks.CheckTrailingWhitespace = 0
- doc8.checks.CheckValidity = 1
~/Desktop/foo/docs is a git repository on main
⊙ doc8 --version julian@Airm ●
1.0.0
flagging the link as an error, but this is incorrect, and make html
will succeed just fine (and produce a page linking to the correct link target).
Starting with version 0.10.1
, the ignore-path
and max-line-length
defined in setup.cfg
fails to be considered.
My configuration is as follows:
[doc8]
max-line-length = 120
ignore-path = docs/_build,docs/autoapi
I call the following command:
doc8 --config "./setup.cfg" "./docs"
With version 0.10.0
, my project outputs:
Scanning...
Validating...
========
Total files scanned = 11
Total files ignored = 18
Total accumulated errors = 0
Detailed error counts:
- doc8.checks.CheckCarriageReturn = 0
- doc8.checks.CheckIndentationNoTab = 0
- doc8.checks.CheckMaxLineLength = 0
- doc8.checks.CheckNewlineEndOfFile = 0
- doc8.checks.CheckTrailingWhitespace = 0
- doc8.checks.CheckValidity = 0
With version 0.10.1
, many errors are reported.
All errors correspond to either a dir supposed to be ignored or a line that is correct in length according to my config (not the default) :
Scanning...
Validating...
/home/francis/dev/devops/makefile/docs/source/references.rst:2: D001 Line too long
/home/francis/dev/devops/makefile/docs/source/toc.rst:6: D001 Line too long
/home/francis/dev/devops/makefile/docs/source/toc.rst:7: D001 Line too long
/home/francis/dev/devops/makefile/docs/source/installation.rst:13: D001 Line too long
/home/francis/dev/devops/makefile/docs/source/installation.rst:14: D001 Line too long
/home/francis/dev/devops/makefile/docs/source/installation.rst:22: D001 Line too long
/home/francis/dev/devops/makefile/docs/source/installation.rst:24: D001 Line too long
/home/francis/dev/devops/makefile/docs/source/installation.rst:25: D001 Line too long
/home/francis/dev/devops/makefile/docs/source/installation.rst:26: D001 Line too long
/home/francis/dev/devops/makefile/docs/_build/html/_sources/README.md.txt:3: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/README.md.txt:3: D001 Line too long
/home/francis/dev/devops/makefile/docs/_build/html/_sources/README.md.txt:4: D001 Line too long
/home/francis/dev/devops/makefile/docs/_build/html/_sources/README.md.txt:7: D001 Line too long
/home/francis/dev/devops/makefile/docs/_build/html/_sources/README.md.txt:8: D001 Line too long
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/index.rst.txt:11: D005 No newline at end of file
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:18: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:23: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:28: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:33: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:38: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:43: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:46: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:48: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:51: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:53: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:56: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:58: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:63: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:68: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:71: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:73: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:76: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:78: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:83: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:86: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:88: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:93: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:96: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:98: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:101: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:103: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:106: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:108: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:111: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:113: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:116: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:118: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:121: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:123: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:126: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:128: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:131: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/__meta__/index.rst.txt:133: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/cli/index.rst.txt:22: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/cli/index.rst.txt:24: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/cli/index.rst.txt:27: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/cli/index.rst.txt:29: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/cli/index.rst.txt:32: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/cli/index.rst.txt:34: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/cli/index.rst.txt:37: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/cli/index.rst.txt:39: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/cli/index.rst.txt:42: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/cli/index.rst.txt:44: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/cli/index.rst.txt:47: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/autoapi/source/cli/index.rst.txt:49: D002 Trailing whitespace
/home/francis/dev/devops/makefile/docs/_build/html/_sources/source/toc.rst.txt:6: D001 Line too long
/home/francis/dev/devops/makefile/docs/_build/html/_sources/source/toc.rst.txt:7: D001 Line too long
/home/francis/dev/devops/makefile/docs/_build/html/_sources/source/references.rst.txt:2: D001 Line too long
/home/francis/dev/devops/makefile/docs/_build/html/_sources/source/references_page.rst.txt:9: D001 Line too long
/home/francis/dev/devops/makefile/docs/_build/html/_sources/source/installation.rst.txt:13: D001 Line too long
/home/francis/dev/devops/makefile/docs/_build/html/_sources/source/installation.rst.txt:14: D001 Line too long
/home/francis/dev/devops/makefile/docs/_build/html/_sources/source/installation.rst.txt:22: D001 Line too long
/home/francis/dev/devops/makefile/docs/_build/html/_sources/source/installation.rst.txt:24: D001 Line too long
/home/francis/dev/devops/makefile/docs/_build/html/_sources/source/installation.rst.txt:25: D001 Line too long
/home/francis/dev/devops/makefile/docs/_build/html/_sources/source/installation.rst.txt:26: D001 Line too long
========
Total files scanned = 29
Total files ignored = 0
Total accumulated errors = 75
Detailed error counts:
- doc8.checks.CheckCarriageReturn = 0
- doc8.checks.CheckIndentationNoTab = 0
- doc8.checks.CheckMaxLineLength = 23
- doc8.checks.CheckNewlineEndOfFile = 1
- doc8.checks.CheckTrailingWhitespace = 51
- doc8.checks.CheckValidity = 0
make: *** [Makefile:1068: check-doc8-only] Error 1
Given a project structure with:
<repo-root>
docs
changes.rst
where doc8
is executed from <repo-root>
Either using --ignore-path-errors "docs/changes.rst;D000"
or setting ignore-path-errors = docs/changes.rst;D000,
in the configuration file does not ignore the error.
Using the absolute file path, the error is properly ignored. However, this is not portable for any repository location.
Example:
.. note:: This is an example not that should be too long for a single line and the linter should report it
IMO directive code
should be ignored but others shouldn't
Configuration for python tools are gradually moving away from *.ini files & setup.cfg to a single, standard file - pyproject.toml.
Index of other tools that have adopted the new standard: https://github.com/carlosperate/awesome-pyproject
Hello!
I have pinned doc8==1.0.0
but yesterday I got error on Python 3.7 on GitHub actions which is in subject, probably it's because your dependency on importlib_metadata was updated to 5.0.0 yesterday, I think it's good idea to pin major versions in your dependencies?
https://github.com/pbelskiy/helix-swarm/actions/runs/3173891210/jobs/5170017639
2022-10-03T11:48:49.7456304Z doc8 run-test: commands[0] | doc8
2022-10-03T11:48:49.8347316Z Scanning...
2022-10-03T11:48:49.8347798Z Validating...
2022-10-03T11:48:49.8357436Z Traceback (most recent call last):
2022-10-03T11:48:49.8368888Z File "/home/runner/work/helix-swarm/helix-swarm/.tox/doc8/lib/python3.7/site-packages/stevedore/_cache.py", line 159, in _get_data_for_path
2022-10-03T11:48:49.8461298Z with open(filename, 'r') as f:
2022-10-03T11:48:49.8466244Z FileNotFoundError: [Errno 2] No such file or directory: '/home/runner/.cache/python-entrypoints/18699aac328cd8d1175a899bc48086260e6edf78e85c27c811b2b7ab7e327a5f'
2022-10-03T11:48:49.8466578Z
2022-10-03T11:48:49.8466750Z During handling of the above exception, another exception occurred:
2022-10-03T11:48:49.8466950Z
2022-10-03T11:48:49.8467062Z Traceback (most recent call last):
2022-10-03T11:48:49.8467573Z File "/home/runner/work/helix-swarm/helix-swarm/.tox/doc8/bin/doc8", line 8, in <module>
2022-10-03T11:48:49.8467879Z sys.exit(main())
2022-10-03T11:48:49.8468375Z File "/home/runner/work/helix-swarm/helix-swarm/.tox/doc8/lib/python3.7/site-packages/doc8/main.py", line 528, in main
2022-10-03T11:48:49.8468714Z result = doc8(args)
2022-10-03T11:48:49.8469186Z File "/home/runner/work/helix-swarm/helix-swarm/.tox/doc8/lib/python3.7/site-packages/doc8/main.py", line 403, in doc8
2022-10-03T11:48:49.8469561Z error_counts = validate(args, files, result=result)
2022-10-03T11:48:49.8470080Z File "/home/runner/work/helix-swarm/helix-swarm/.tox/doc8/lib/python3.7/site-packages/doc8/main.py", line 239, in validate
2022-10-03T11:48:49.8470425Z for c in fetch_checks(cfg):
2022-10-03T11:48:49.8470927Z File "/home/runner/work/helix-swarm/helix-swarm/.tox/doc8/lib/python3.7/site-packages/doc8/main.py", line 183, in fetch_checks
2022-10-03T11:48:49.8471530Z namespace="doc8.extension.check", invoke_on_load=True, invoke_args=(cfg.copy(),)
2022-10-03T11:48:49.8472117Z File "/home/runner/work/helix-swarm/helix-swarm/.tox/doc8/lib/python3.7/site-packages/stevedore/extension.py", line 136, in __init__
2022-10-03T11:48:49.8472459Z verify_requirements)
2022-10-03T11:48:49.8472975Z File "/home/runner/work/helix-swarm/helix-swarm/.tox/doc8/lib/python3.7/site-packages/stevedore/extension.py", line 218, in _load_plugins
2022-10-03T11:48:49.8473377Z for ep in self.list_entry_points():
2022-10-03T11:48:49.8473953Z File "/home/runner/work/helix-swarm/helix-swarm/.tox/doc8/lib/python3.7/site-packages/stevedore/extension.py", line 207, in list_entry_points
2022-10-03T11:48:49.8474362Z eps = list(_cache.get_group_all(self.namespace))
2022-10-03T11:48:49.8474907Z File "/home/runner/work/helix-swarm/helix-swarm/.tox/doc8/lib/python3.7/site-packages/stevedore/_cache.py", line 179, in get_group_all
2022-10-03T11:48:49.8475272Z data = self._get_data_for_path(path)
2022-10-03T11:48:49.8475896Z File "/home/runner/work/helix-swarm/helix-swarm/.tox/doc8/lib/python3.7/site-packages/stevedore/_cache.py", line 162, in _get_data_for_path
2022-10-03T11:48:49.8476270Z data = _build_cacheable_data(path)
2022-10-03T11:48:49.8476816Z File "/home/runner/work/helix-swarm/helix-swarm/.tox/doc8/lib/python3.7/site-packages/stevedore/_cache.py", line 110, in _build_cacheable_data
2022-10-03T11:48:49.8477207Z for name, group_data in real_groups.items():
2022-10-03T11:48:49.8477592Z AttributeError: 'EntryPoints' object has no attribute 'items'
2022-10-03T11:48:49.8478094Z ERROR: InvocationError for command /home/runner/work/helix-swarm/helix-swarm/.tox/doc8/bin/doc8 (exited with code 1)
I tried used two versions of what it was supposed to be config in toml file and I observed that running doc8
failed to use the ignore. On the other hand putting configuration inside setup.cfg
worked.
# pyproject.toml
[tool.doc8]
ignore-path = [".tox"]
# pyproject.toml
[tool.doc8]
ignore-path = ".tox"
None of these works and based on docs, at least should have worked.
According to the style guide there should be a blank line under a directive that does not fit in one line.
Meaning, this is incorrect:
.. note: This directive has incorrect syntax according to
sphinx style guide documentation
Instead the correct is this:
.. note::
This directive has correct multiline syntax
and does abide by the style guide
It has been more than two years since the last release of this project on PyPI: https://pypi.org/project/doc8/#history
Any plans to push a new release?
I'm using a pyproject.toml file to setup my lib tools and I would like to include doc8. I wrote the following:
[tool.doc8]
ignore = ["D001"] # we follow a 1 line = 1 paragraph style
ignore-path-errors = "docs/source/index.rst;D000"
but when I try to run doc8 I got the following error :
Traceback (most recent call last):
File "/Users/pierrickrambaud/.pyenv/versions/3.8.3/lib/python3.8/runpy.py", line 194, in _run_module_as_main
return _run_code(code, main_globals, None,
File "/Users/pierrickrambaud/.pyenv/versions/3.8.3/lib/python3.8/runpy.py", line 87, in _run_code
exec(code, run_globals)
File "/Users/pierrickrambaud/.cache/pre-commit/repos8mnpfl6/py_env-python3/lib/python3.8/site-packages/doc8/main.py", line 20, in
sys.exit(main.main())
File "/Users/pierrickrambaud/.cache/pre-commit/repos8mnpfl6/py_env-python3/lib/python3.8/site-packages/doc8/main.py", line 534, in main
result = doc8(args)
File "/Users/pierrickrambaud/.cache/pre-commit/repos8mnpfl6/py_env-python3/lib/python3.8/site-packages/doc8/main.py", line 385, in doc8
cfg = extract_config(args)
File "/Users/pierrickrambaud/.cache/pre-commit/repos8mnpfl6/py_env-python3/lib/python3.8/site-packages/doc8/main.py", line 167, in extract_config
cfg = from_toml(cfg_file)
File "/Users/pierrickrambaud/.cache/pre-commit/repos8mnpfl6/py_env-python3/lib/python3.8/site-packages/doc8/main.py", line 149, in from_toml
value = parse_ignore_path_errors(value)
File "/Users/pierrickrambaud/.cache/pre-commit/repos8mnpfl6/py_env-python3/lib/python3.8/site-packages/doc8/main.py", line 79, in parse_ignore_path_errors
path, ignored_errors = path.split(";", 1)
ValueError: not enough values to unpack (expected 2, got 1)
What I don't understand is that I do use a ";" in my parameter string an I do have 2 values:
Am I missing something ?
I'm using the pre-commit hook of this repository and some of the errors pointed by doc8 are super simple to correct (I'm thonking about trailing whitespace and missing return at end of file.
How hard would it be to modify the files on the fly ? the same way, black and ruff are actually fixing some issues automatically.
stevedore lacks types and is not actively maintained, we need to get rid of it.
Any PR is welcomed. My guess is that pluggy might be a good guess.
I am not sure how many are using extensions, as if nothing happens we might just remove the support for extensions and bump the major version, at least until someone using extensions readds the support.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.