{"id":13367681,"url":"https://github.com/PyCQA/doc8","last_synced_at":"2025-03-12T20:30:49.556Z","repository":{"id":17485839,"uuid":"20267783","full_name":"PyCQA/doc8","owner":"PyCQA","description":"Style checker for sphinx (or other) rst documentation.","archived":false,"fork":false,"pushed_at":"2025-02-17T22:43:51.000Z","size":295,"stargazers_count":166,"open_issues_count":23,"forks_count":36,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-03-05T15:53:38.244Z","etag":null,"topics":["hacktoberfest","linter","pep-621","pre-commit-hook","python"],"latest_commit_sha":null,"homepage":"https://github.com/PyCQA/doc8","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PyCQA.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":"CONTRIBUTING.rst","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"ssbarnea"}},"created_at":"2014-05-28T18:23:05.000Z","updated_at":"2025-02-01T18:53:57.000Z","dependencies_parsed_at":"2023-02-16T19:45:48.122Z","dependency_job_id":"4e0c9f8e-3681-47be-be54-a279a0564580","html_url":"https://github.com/PyCQA/doc8","commit_stats":{"total_commits":231,"total_committers":46,"mean_commits":5.021739130434782,"dds":0.7445887445887446,"last_synced_commit":"84dc64257910f07bb1e8291a42fa0c47c37bfa5b"},"previous_names":["openstack/doc8"],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PyCQA%2Fdoc8","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PyCQA%2Fdoc8/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PyCQA%2Fdoc8/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PyCQA%2Fdoc8/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PyCQA","download_url":"https://codeload.github.com/PyCQA/doc8/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243165538,"owners_count":20246725,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","linter","pep-621","pre-commit-hook","python"],"created_at":"2024-07-30T00:02:00.348Z","updated_at":"2025-03-12T20:30:49.529Z","avatar_url":"https://github.com/PyCQA.png","language":"Python","readme":".. image:: https://img.shields.io/pypi/v/doc8?logo=python\u0026logoColor=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\u0026logo=github\u0026logoColor=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\u0026logoColor=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","funding_links":["https://github.com/sponsors/ssbarnea"],"categories":["Linters","Python"],"sub_categories":["reStructuredText"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPyCQA%2Fdoc8","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FPyCQA%2Fdoc8","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPyCQA%2Fdoc8/lists"}