| Name | doc8 JSON |
| Version |
1.1.1
JSON |
| download |
| home_page | |
| Summary | Style checker for Sphinx (or other) RST documentation |
| upload_time | 2022-12-24 15:04:52 |
| maintainer | |
| docs_url | None |
| author | |
| 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
:alt: PyPI
:target: https://pypi.org/project/doc8/
.. image:: https://github.com/PyCQA/doc8/workflows/tox/badge.svg
:target: https://github.com/PyCQA/doc8/actions
:alt: CI
.. image:: https://img.shields.io/pypi/l/doc8
:alt: PyPI - License
.. image:: https://img.shields.io/github/last-commit/pycqa/doc8
:alt: GitHub last commit
====
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
**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": "",
"name": "doc8",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "PyCQA <code-quality@python.org>",
"keywords": "doc8,rst,linter",
"author": "",
"author_email": "OpenStack <openstack-discuss@lists.openstack.org>",
"download_url": "https://files.pythonhosted.org/packages/a1/b5/63a2f2ceba95be5cc15813fd310d560264e8662dbd7495669a1e26d59026/doc8-1.1.1.tar.gz",
"platform": null,
"description": ".. image:: https://img.shields.io/pypi/v/doc8\n :alt: PyPI\n :target: https://pypi.org/project/doc8/\n\n.. image:: https://github.com/PyCQA/doc8/workflows/tox/badge.svg\n :target: https://github.com/PyCQA/doc8/actions\n :alt: CI\n\n.. image:: https://img.shields.io/pypi/l/doc8\n :alt: PyPI - License\n\n.. image:: https://img.shields.io/github/last-commit/pycqa/doc8\n :alt: GitHub last commit\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**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.1",
"split_keywords": [
"doc8",
"rst",
"linter"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "45cb9d79b2ec05e0b078170dae038f47",
"sha256": "e493aa3f36820197c49f407583521bb76a0fde4fffbcd0e092be946ff95931ac"
},
"downloads": -1,
"filename": "doc8-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "45cb9d79b2ec05e0b078170dae038f47",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 25495,
"upload_time": "2022-12-24T15:04:51",
"upload_time_iso_8601": "2022-12-24T15:04:51.055305Z",
"url": "https://files.pythonhosted.org/packages/3e/68/2f230017092b5f166a6fa03d7dde4b209b33d18d294ad4b1abdadb1060a3/doc8-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "672d96a10c68abc6848449508d6153e8",
"sha256": "d97a93e8f5a2efc4713a0804657dedad83745cca4cd1d88de9186f77f9776004"
},
"downloads": -1,
"filename": "doc8-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "672d96a10c68abc6848449508d6153e8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 26514,
"upload_time": "2022-12-24T15:04:52",
"upload_time_iso_8601": "2022-12-24T15:04:52.374075Z",
"url": "https://files.pythonhosted.org/packages/a1/b5/63a2f2ceba95be5cc15813fd310d560264e8662dbd7495669a1e26d59026/doc8-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-24 15:04:52",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "doc8"
}
