| Name | doc8 JSON |
| Version |
1.1.2
JSON |
| download |
| home_page | None |
| Summary | Style checker for Sphinx (or other) RST documentation |
| upload_time | 2024-09-02 13:11:12 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | Apache 2.0 |
| keywords |
doc8
rst
linter
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
.. image:: https://img.shields.io/pypi/v/doc8?logo=python&logoColor=white
:target: https://pypi.org/project/doc8/
:alt: PyPI
.. image:: https://img.shields.io/github/actions/workflow/status/PyCQA/doc8/tox.yml?label=tox&logo=github&logoColor=white
:target: https://github.com/PyCQA/doc8/actions
:alt: CI
.. image:: https://img.shields.io/pypi/l/doc8
:target: https://github.com/PyCQA/doc8/blob/main/LICENSE
:alt: PyPI - License
.. image:: https://img.shields.io/github/last-commit/pycqa/doc8
:target: https://github.com/PyCQA/doc8/commits/main
:alt: GitHub last commit
.. image:: https://img.shields.io/readthedocs/doc8/stable?logo=readthedocs&logoColor=white
:target: https://doc8.readthedocs.io/en/stable/index.html
:alt: Read the Docs (stable)
====
doc8
====
*doc8* is an *opinionated* style checker for rst__ (with basic support for
plain text) styles of documentation.
__ http://docutils.sourceforge.net/docs/ref/rst/introduction.html
Quick start
-----------
::
pip install doc8
To run *doc8*, just invoke it against any documentation directory::
$ doc8 cool-project/docs
Usage
-----
::
$ doc8 -h
usage: doc8 [-h] [--config path] [--allow-long-titles] [--ignore code]
[--no-sphinx] [--ignore-path path] [--ignore-path-errors path]
[--default-extension extension] [--file-encoding encoding]
[--max-line-length int] [-e extension] [-v] [--version]
[path [path ...]]
Check documentation for simple style requirements.
What is checked:
- invalid RST format - D000
- lines should not be longer than 79 characters - D001
- RST exception: line with no whitespace except in the beginning
- RST exception: lines with http or https urls
- RST exception: literal blocks
- RST exception: rst target directives
- no trailing whitespace - D002
- no tabulation for indentation - D003
- no carriage returns (use unix newlines) - D004
- no newline at end of file - D005
positional arguments:
path Path to scan for doc files (default: current
directory).
optional arguments:
-h, --help show this help message and exit
--config path user config file location (default: .config/doc8.ini, doc8.ini, tox.ini,
pep8.ini, setup.cfg).
--allow-long-titles allow long section titles (default: false).
--ignore code ignore the given error code(s).
--no-sphinx do not ignore sphinx specific false positives.
--ignore-path path ignore the given directory or file (globs are
supported).
--ignore-path-errors path
ignore the given specific errors in the provided file.
--default-extension extension
default file extension to use when a file is found
without a file extension.
--file-encoding encoding
set input files text encoding
--max-line-length int
maximum allowed line length (default: 79).
-e extension, --extension extension
check file extensions of the given type (default:
.rst, .txt).
-q, --quiet only print violations
-v, --verbose run in verbose mode.
--version show the version and exit.
INI file usage
~~~~~~~~~~~~~~
Instead of using the CLI for options the following files will also be examined
for ``[doc8]`` sections that can also provide the same set of options. If
the ``--config path`` option is used, these files will **not** be scanned for
the current working directory and that configuration path will be used
instead.
* ``$CWD/doc8.ini``
* ``$CWD/.config/doc8.ini``
* ``$CWD/tox.ini``
* ``$CWD/pep8.ini``
* ``$CWD/setup.cfg``
* ``$CWD/pyproject.toml``
An example section that can be placed into one of these files::
[doc8]
ignore-path=/tmp/stuff,/tmp/other_stuff
max-line-length=99
verbose=1
ignore-path-errors=/tmp/other_thing.rst;D001;D002
An example for the ``pyproject.toml`` file::
[tool.doc8]
ignore = ["D001"]
allow-long-titles = true
**Note:** The option names are the same as the command line ones (with the
only variation of this being the ``no-sphinx`` option which from the
configuration file will be ``sphinx`` instead).
Option conflict resolution
~~~~~~~~~~~~~~~~~~~~~~~~~~
When the same option is passed on the command line and also via configuration
files the following strategies are applied to resolve these types of conflicts.
====================== =========== ========
Option Overrides Merges
====================== =========== ========
``allow-long-titles`` Yes No
``ignore-path-errors`` No Yes
``default-extension`` Yes No
``extension`` No Yes
``ignore-path`` No Yes
``ignore`` No Yes
``max-line-length`` Yes No
``file-encoding`` Yes No
``sphinx`` Yes No
====================== =========== ========
**Note:** In the above table the configuration file option when specified as
*overrides* will replace the same option given via the command line. When
*merges* is stated then the option will be combined with the command line
option (for example by becoming a larger list or set of values that contains
the values passed on the command line *and* the values passed via
configuration).
API
---
It is also possible to use *doc8* programmatically. To call *doc8* from a
Python project, use::
from doc8 import doc8
result = doc8(allow_long_titles=True, max_line_length=99)
The returned ``result`` will have the following attributes and methods:
* ``result.files_selected`` - number of files selected
* ``result.files_ignored`` - number of files ignored
* ``result.error_counts`` - ``dict`` of ``{check_name: error_count}``
* ``result.total_errors`` - total number of errors found
* ``result.errors`` - list of
``(check_name, filename, line_num, code, message)`` tuples
* ``result.report()`` - returns a human-readable report as a string
The ``doc8`` method accepts the same arguments as the executable. Simply
replace hyphens with underscores.
**Note:** Calling ``doc8`` in this way will not write to stdout, so the
``quiet`` and ``verbose`` options are ignored.
Raw data
{
"_id": null,
"home_page": null,
"name": "doc8",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "PyCQA <code-quality@python.org>",
"keywords": "doc8, rst, linter",
"author": null,
"author_email": "OpenStack <openstack-discuss@lists.openstack.org>",
"download_url": "https://files.pythonhosted.org/packages/11/28/b0a576233730b756ca1ebb422bc6199a761b826b86e93e5196dfa85331ea/doc8-1.1.2.tar.gz",
"platform": null,
"description": ".. image:: https://img.shields.io/pypi/v/doc8?logo=python&logoColor=white\n :target: https://pypi.org/project/doc8/\n :alt: PyPI\n\n.. image:: https://img.shields.io/github/actions/workflow/status/PyCQA/doc8/tox.yml?label=tox&logo=github&logoColor=white\n :target: https://github.com/PyCQA/doc8/actions\n :alt: CI\n\n.. image:: https://img.shields.io/pypi/l/doc8\n :target: https://github.com/PyCQA/doc8/blob/main/LICENSE\n :alt: PyPI - License\n\n.. image:: https://img.shields.io/github/last-commit/pycqa/doc8\n :target: https://github.com/PyCQA/doc8/commits/main\n :alt: GitHub last commit\n\n.. image:: https://img.shields.io/readthedocs/doc8/stable?logo=readthedocs&logoColor=white\n :target: https://doc8.readthedocs.io/en/stable/index.html\n :alt: Read the Docs (stable)\n\n====\ndoc8\n====\n\n*doc8* is an *opinionated* style checker for rst__ (with basic support for\nplain text) styles of documentation.\n\n__ http://docutils.sourceforge.net/docs/ref/rst/introduction.html\n\nQuick start\n-----------\n\n::\n\n pip install doc8\n\nTo run *doc8*, just invoke it against any documentation directory::\n\n $ doc8 cool-project/docs\n\nUsage\n-----\n\n::\n\n $ doc8 -h\n\n usage: doc8 [-h] [--config path] [--allow-long-titles] [--ignore code]\n [--no-sphinx] [--ignore-path path] [--ignore-path-errors path]\n [--default-extension extension] [--file-encoding encoding]\n [--max-line-length int] [-e extension] [-v] [--version]\n [path [path ...]]\n\n Check documentation for simple style requirements.\n\n What is checked:\n - invalid RST format - D000\n - lines should not be longer than 79 characters - D001\n - RST exception: line with no whitespace except in the beginning\n - RST exception: lines with http or https urls\n - RST exception: literal blocks\n - RST exception: rst target directives\n - no trailing whitespace - D002\n - no tabulation for indentation - D003\n - no carriage returns (use unix newlines) - D004\n - no newline at end of file - D005\n\n positional arguments:\n path Path to scan for doc files (default: current\n directory).\n\n optional arguments:\n -h, --help show this help message and exit\n --config path user config file location (default: .config/doc8.ini, doc8.ini, tox.ini,\n pep8.ini, setup.cfg).\n --allow-long-titles allow long section titles (default: false).\n --ignore code ignore the given error code(s).\n --no-sphinx do not ignore sphinx specific false positives.\n --ignore-path path ignore the given directory or file (globs are\n supported).\n --ignore-path-errors path\n ignore the given specific errors in the provided file.\n --default-extension extension\n default file extension to use when a file is found\n without a file extension.\n --file-encoding encoding\n set input files text encoding\n --max-line-length int\n maximum allowed line length (default: 79).\n -e extension, --extension extension\n check file extensions of the given type (default:\n .rst, .txt).\n -q, --quiet only print violations\n -v, --verbose run in verbose mode.\n --version show the version and exit.\n\nINI file usage\n~~~~~~~~~~~~~~\n\nInstead of using the CLI for options the following files will also be examined\nfor ``[doc8]`` sections that can also provide the same set of options. If\nthe ``--config path`` option is used, these files will **not** be scanned for\nthe current working directory and that configuration path will be used\ninstead.\n\n* ``$CWD/doc8.ini``\n* ``$CWD/.config/doc8.ini``\n* ``$CWD/tox.ini``\n* ``$CWD/pep8.ini``\n* ``$CWD/setup.cfg``\n* ``$CWD/pyproject.toml``\n\nAn example section that can be placed into one of these files::\n\n [doc8]\n\n ignore-path=/tmp/stuff,/tmp/other_stuff\n max-line-length=99\n verbose=1\n ignore-path-errors=/tmp/other_thing.rst;D001;D002\n\n\nAn example for the ``pyproject.toml`` file::\n\n [tool.doc8]\n\n ignore = [\"D001\"]\n allow-long-titles = true\n\n**Note:** The option names are the same as the command line ones (with the\nonly variation of this being the ``no-sphinx`` option which from the\nconfiguration file will be ``sphinx`` instead).\n\nOption conflict resolution\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nWhen the same option is passed on the command line and also via configuration\nfiles the following strategies are applied to resolve these types of conflicts.\n\n====================== =========== ========\nOption Overrides Merges\n====================== =========== ========\n``allow-long-titles`` Yes No\n``ignore-path-errors`` No Yes\n``default-extension`` Yes No\n``extension`` No Yes\n``ignore-path`` No Yes\n``ignore`` No Yes\n``max-line-length`` Yes No\n``file-encoding`` Yes No\n``sphinx`` Yes No\n====================== =========== ========\n\n**Note:** In the above table the configuration file option when specified as\n*overrides* will replace the same option given via the command line. When\n*merges* is stated then the option will be combined with the command line\noption (for example by becoming a larger list or set of values that contains\nthe values passed on the command line *and* the values passed via\nconfiguration).\n\n\nAPI\n---\n\nIt is also possible to use *doc8* programmatically. To call *doc8* from a\nPython project, use::\n\n from doc8 import doc8\n\n result = doc8(allow_long_titles=True, max_line_length=99)\n\nThe returned ``result`` will have the following attributes and methods:\n\n* ``result.files_selected`` - number of files selected\n* ``result.files_ignored`` - number of files ignored\n* ``result.error_counts`` - ``dict`` of ``{check_name: error_count}``\n* ``result.total_errors`` - total number of errors found\n* ``result.errors`` - list of\n ``(check_name, filename, line_num, code, message)`` tuples\n* ``result.report()`` - returns a human-readable report as a string\n\nThe ``doc8`` method accepts the same arguments as the executable. Simply\nreplace hyphens with underscores.\n\n**Note:** Calling ``doc8`` in this way will not write to stdout, so the\n``quiet`` and ``verbose`` options are ignored.\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Style checker for Sphinx (or other) RST documentation",
"version": "1.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/pycqa/doc8/issues",
"CI": "https://github.com/pycqa/doc8/actions",
"Discussions": "https://github.com/pycqa/doc8/discussions",
"Documentation": "https://doc8.readthedocs.io",
"Homepage": "https://github.com/pycqa/doc8",
"Release Management": "https://github.com/pycqa/doc8/releases"
},
"split_keywords": [
"doc8",
" rst",
" linter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0cf16ffd5d76578e98a8f21ae7216b88a7212c778f665f1a8f4f8ce6f9605da4",
"md5": "c69cec77f491c5f8e9f2d4ed11f4a1e1",
"sha256": "e787b3076b391b8b49400da5d018bacafe592dfc0a04f35a9be22d0122b82b59"
},
"downloads": -1,
"filename": "doc8-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c69cec77f491c5f8e9f2d4ed11f4a1e1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 25794,
"upload_time": "2024-09-02T13:11:10",
"upload_time_iso_8601": "2024-09-02T13:11:10.830349Z",
"url": "https://files.pythonhosted.org/packages/0c/f1/6ffd5d76578e98a8f21ae7216b88a7212c778f665f1a8f4f8ce6f9605da4/doc8-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1128b0a576233730b756ca1ebb422bc6199a761b826b86e93e5196dfa85331ea",
"md5": "d0dce7c0e26b0080a882168862dcf4a5",
"sha256": "1225f30144e1cc97e388dbaf7fe3e996d2897473a53a6dae268ddde21c354b98"
},
"downloads": -1,
"filename": "doc8-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "d0dce7c0e26b0080a882168862dcf4a5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 27030,
"upload_time": "2024-09-02T13:11:12",
"upload_time_iso_8601": "2024-09-02T13:11:12.146196Z",
"url": "https://files.pythonhosted.org/packages/11/28/b0a576233730b756ca1ebb422bc6199a761b826b86e93e5196dfa85331ea/doc8-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-02 13:11:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pycqa",
"github_project": "doc8",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "doc8"
}
