restructuredtext-lint
=====================
.. image:: https://travis-ci.org/twolfson/restructuredtext-lint.png?branch=master
:target: https://travis-ci.org/twolfson/restructuredtext-lint
:alt: Build Status
`reStructuredText`_ `linter`_
This was created out of frustration with `PyPI`_; it sucks finding out your `reST`_ is invalid **after** uploading it. It is being developed in junction with a `Sublime Text`_ linter.
.. _`reStructuredText`: http://docutils.sourceforge.net/rst.html
.. _`linter`: http://en.wikipedia.org/wiki/Lint_%28software%29
.. _`reST`: `reStructuredText`_
.. _`PyPI`: http://pypi.python.org/
.. _`Sublime Text`: http://sublimetext.com/
Getting Started
---------------
Install the module with: ``pip install restructuredtext_lint``
.. code:: python
import restructuredtext_lint
errors = restructuredtext_lint.lint("""
Hello World
=======
""")
# `errors` will be list of system messages
# [<system_message: <paragraph...><literal_block...>>]
errors[0].message # Title underline too short.
CLI Utility
^^^^^^^^^^^
For your convenience, we present a CLI utility ``rst-lint`` (also available as ``restructuredtext-lint``).
.. code:: console
$ rst-lint --help
usage: rst-lint [-h] [--version] [--format {text,json}] [--encoding ENCODING]
[--level {debug,info,warning,error,severe}]
[--rst-prolog RST_PROLOG]
path [path ...]
Lint reStructuredText files. Returns 0 if all files pass linting, 1 for an
internal error, and 2 if linting failed.
positional arguments:
path File/folder to lint
optional arguments:
-h, --help show this help message and exit
--version show program's version number and exit
--format {text,json} Format of the output (default: "text")
--encoding ENCODING Encoding of the input file (e.g. "utf-8")
--level {debug,info,warning,error,severe}
Minimum error level to report (default: "warning")
--rst-prolog RST_PROLOG
reStructuredText content to prepend to all files
(useful for substitutions)
$ rst-lint README.rst
WARNING README.rst:2 Title underline too short.
Other tools
^^^^^^^^^^^
``restructuredtext-lint`` is also integrated in other tools. A list can be found and updated in our wiki
https://github.com/twolfson/restructuredtext-lint/wiki/Integration-in-other-tools
PyPI issues
^^^^^^^^^^^
While a document may lint cleanly locally, there can be issues when submitted it to `PyPI`_. Here are some common problems:
- Usage of non-builtin lexers (e.g. ``bibtex``) will pass locally but not be recognized/parsable on `PyPI`_
- This is due to `PyPI`_ not having a non-builtin lexer installed
- Please avoid non-builtin lexers to avoid complications
- For more information, see `#27`_
- Relative hyperlinks will not work (e.g. ``./UNLICENSE``)
- According to Stack Overflow, hyperlinks must use a scheme (e.g. ``http``, ``https``) and that scheme must be whitelisted
- http://stackoverflow.com/a/16594755
- Please use absolute hyperlinks (e.g. ``https://github.com/twolfson/restructuredtext-lint/blob/master/UNLICENSE``)
.. _`#27`: https://github.com/twolfson/restructuredtext-lint/issues/27
Documentation
-------------
``restructuredtext-lint`` exposes a ``lint`` and ``lint_file`` function
``restructuredtext_lint.lint(content, filepath=None, rst_prolog=None)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Lint `reStructuredText`_ and return errors
- content ``String`` - `reStructuredText`_ to be linted
- filepath ``String`` - Optional path to file, this will be returned as the source
- rst_prolog ``String`` - Optional content to prepend to content, line numbers will be offset to ignore this
Returns:
- errors ``List`` - List of errors
- Each error is a class from `docutils`_ with the following attrs
- line ``Integer|None`` - Line where the error occurred
- On rare occasions, this will be ``None`` (e.g. anonymous link mismatch)
- source ``String`` - ``filepath`` provided in parameters
- level ``Integer`` - Level of the warning
- Levels represent 'info': 1, 'warning': 2, 'error': 3, 'severe': 4
- type ``String`` - Noun describing the error level
- Levels can be 'INFO', 'WARNING', 'ERROR', or 'SEVERE'
- message ``String`` - Error message
- full_message ``String`` - Error message and source lines where the error occurred
- It should be noted that ``level``, ``type``, ``message``, and ``full_message`` are custom attrs added onto the original ``system_message``
.. _`docutils`: http://docutils.sourceforge.net/
``restructuredtext_lint.lint_file(filepath, encoding=None, *args, **kwargs)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Lint a `reStructuredText`_ file and return errors
- filepath ``String`` - Path to file for linting
- encoding ``String`` - Encoding to read file in as
- When ``None`` is provided, it will use OS default as provided by `locale.getpreferredencoding`_
- The list of supported encodings can be found at http://docs.python.org/2/library/codecs.html#standard-encodings
- ``*args`` - Additional arguments to be passed to ``lint``
- ``**kwargs`` - Additional keyword arguments to be passed to ``lint``
.. _`locale.getpreferredencoding`: http://docs.python.org/2/library/locale.html#locale.getpreferredencoding
Returns: Same structure as ``restructuredtext_lint.lint``
Extension
---------
Under the hood, we leverage `docutils`_ for parsing reStructuredText documents. `docutils`_ supports adding new directives and roles via ``register_directive`` and ``register_role``.
Sphinx
^^^^^^
Unfortunately due to customizations in `Sphinx's parser`_ we cannot include all of its directives/roles (see `#29`_). However, we can include some of them as one-offs. Here is an example of adding a directive from `Sphinx`_.
.. _`Sphinx`: http://sphinx-doc.org/
.. _`Sphinx's parser`: Sphinx_
.. _`#29`: https://github.com/twolfson/restructuredtext-lint/issues/29#issuecomment-243456787
https://github.com/sphinx-doc/sphinx/blob/1.3/sphinx/directives/code.py
**sphinx.rst**
.. code:: rst
Hello
=====
World
.. highlight:: python
Hello World!
**sphinx.py**
.. code:: python
# Load in our dependencies
from docutils.parsers.rst.directives import register_directive
from sphinx.directives.code import Highlight
import restructuredtext_lint
# Load our new directive
register_directive('highlight', Highlight)
# Lint our README
errors = restructuredtext_lint.lint_file('docs/sphinx/README.rst')
print errors[0].message # Error in "highlight" directive: no content permitted.
Examples
--------
Here is an example of all invalid properties
.. code:: python
rst = """
Some content.
Hello World
=======
Some more content!
"""
errors = restructuredtext_lint.lint(rst, 'myfile.py')
errors[0].line # 5
errors[0].source # myfile.py
errors[0].level # 2
errors[0].type # WARNING
errors[0].message # Title underline too short.
errors[0].full_message # Title underline too short.
#
# Hello World
# =======
Contributing
------------
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Test via ``nosetests``.
Donating
--------
Support this project and `others by twolfson`_ via `donations`_.
http://twolfson.com/support-me
.. _`others by twolfson`: http://twolfson.com/projects
.. _donations: http://twolfson.com/support-me
Unlicense
---------
As of Nov 22 2013, Todd Wolfson has released this repository and its contents to the public domain.
It has been released under the `UNLICENSE`_.
.. _UNLICENSE: https://github.com/twolfson/restructuredtext-lint/blob/master/UNLICENSE
Raw data
{
"_id": null,
"home_page": "https://github.com/twolfson/restructuredtext-lint",
"name": "restructuredtext-lint",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "restructuredtext,restructured text,rest,rst,lint",
"author": "Todd Wolfson",
"author_email": "todd@twolfson.com",
"download_url": "https://files.pythonhosted.org/packages/48/9c/6d8035cafa2d2d314f34e6cd9313a299de095b26e96f1c7312878f988eec/restructuredtext_lint-1.4.0.tar.gz",
"platform": "",
"description": "restructuredtext-lint\n=====================\n\n.. image:: https://travis-ci.org/twolfson/restructuredtext-lint.png?branch=master\n :target: https://travis-ci.org/twolfson/restructuredtext-lint\n :alt: Build Status\n\n`reStructuredText`_ `linter`_\n\nThis was created out of frustration with `PyPI`_; it sucks finding out your `reST`_ is invalid **after** uploading it. It is being developed in junction with a `Sublime Text`_ linter.\n\n.. _`reStructuredText`: http://docutils.sourceforge.net/rst.html\n.. _`linter`: http://en.wikipedia.org/wiki/Lint_%28software%29\n.. _`reST`: `reStructuredText`_\n.. _`PyPI`: http://pypi.python.org/\n.. _`Sublime Text`: http://sublimetext.com/\n\nGetting Started\n---------------\nInstall the module with: ``pip install restructuredtext_lint``\n\n.. code:: python\n\n import restructuredtext_lint\n errors = restructuredtext_lint.lint(\"\"\"\n Hello World\n =======\n \"\"\")\n\n # `errors` will be list of system messages\n # [<system_message: <paragraph...><literal_block...>>]\n errors[0].message # Title underline too short.\n\nCLI Utility\n^^^^^^^^^^^\nFor your convenience, we present a CLI utility ``rst-lint`` (also available as ``restructuredtext-lint``).\n\n.. code:: console\n\n $ rst-lint --help\n usage: rst-lint [-h] [--version] [--format {text,json}] [--encoding ENCODING]\n [--level {debug,info,warning,error,severe}]\n [--rst-prolog RST_PROLOG]\n path [path ...]\n\n Lint reStructuredText files. Returns 0 if all files pass linting, 1 for an\n internal error, and 2 if linting failed.\n\n positional arguments:\n path File/folder to lint\n\n optional arguments:\n -h, --help show this help message and exit\n --version show program's version number and exit\n --format {text,json} Format of the output (default: \"text\")\n --encoding ENCODING Encoding of the input file (e.g. \"utf-8\")\n --level {debug,info,warning,error,severe}\n Minimum error level to report (default: \"warning\")\n --rst-prolog RST_PROLOG\n reStructuredText content to prepend to all files\n (useful for substitutions)\n\n $ rst-lint README.rst\n WARNING README.rst:2 Title underline too short.\n\nOther tools\n^^^^^^^^^^^\n``restructuredtext-lint`` is also integrated in other tools. A list can be found and updated in our wiki\n\nhttps://github.com/twolfson/restructuredtext-lint/wiki/Integration-in-other-tools\n\nPyPI issues\n^^^^^^^^^^^\nWhile a document may lint cleanly locally, there can be issues when submitted it to `PyPI`_. Here are some common problems:\n\n- Usage of non-builtin lexers (e.g. ``bibtex``) will pass locally but not be recognized/parsable on `PyPI`_\n\n - This is due to `PyPI`_ not having a non-builtin lexer installed\n - Please avoid non-builtin lexers to avoid complications\n - For more information, see `#27`_\n\n- Relative hyperlinks will not work (e.g. ``./UNLICENSE``)\n\n - According to Stack Overflow, hyperlinks must use a scheme (e.g. ``http``, ``https``) and that scheme must be whitelisted\n\n - http://stackoverflow.com/a/16594755\n\n - Please use absolute hyperlinks (e.g. ``https://github.com/twolfson/restructuredtext-lint/blob/master/UNLICENSE``)\n\n.. _`#27`: https://github.com/twolfson/restructuredtext-lint/issues/27\n\nDocumentation\n-------------\n``restructuredtext-lint`` exposes a ``lint`` and ``lint_file`` function\n\n``restructuredtext_lint.lint(content, filepath=None, rst_prolog=None)``\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nLint `reStructuredText`_ and return errors\n\n- content ``String`` - `reStructuredText`_ to be linted\n- filepath ``String`` - Optional path to file, this will be returned as the source\n- rst_prolog ``String`` - Optional content to prepend to content, line numbers will be offset to ignore this\n\nReturns:\n\n- errors ``List`` - List of errors\n\n - Each error is a class from `docutils`_ with the following attrs\n\n - line ``Integer|None`` - Line where the error occurred\n\n - On rare occasions, this will be ``None`` (e.g. anonymous link mismatch)\n\n - source ``String`` - ``filepath`` provided in parameters\n - level ``Integer`` - Level of the warning\n\n - Levels represent 'info': 1, 'warning': 2, 'error': 3, 'severe': 4\n\n - type ``String`` - Noun describing the error level\n\n - Levels can be 'INFO', 'WARNING', 'ERROR', or 'SEVERE'\n - message ``String`` - Error message\n - full_message ``String`` - Error message and source lines where the error occurred\n\n - It should be noted that ``level``, ``type``, ``message``, and ``full_message`` are custom attrs added onto the original ``system_message``\n\n.. _`docutils`: http://docutils.sourceforge.net/\n\n``restructuredtext_lint.lint_file(filepath, encoding=None, *args, **kwargs)``\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nLint a `reStructuredText`_ file and return errors\n\n- filepath ``String`` - Path to file for linting\n- encoding ``String`` - Encoding to read file in as\n\n - When ``None`` is provided, it will use OS default as provided by `locale.getpreferredencoding`_\n - The list of supported encodings can be found at http://docs.python.org/2/library/codecs.html#standard-encodings\n\n- ``*args`` - Additional arguments to be passed to ``lint``\n- ``**kwargs`` - Additional keyword arguments to be passed to ``lint``\n\n.. _`locale.getpreferredencoding`: http://docs.python.org/2/library/locale.html#locale.getpreferredencoding\n\nReturns: Same structure as ``restructuredtext_lint.lint``\n\nExtension\n---------\nUnder the hood, we leverage `docutils`_ for parsing reStructuredText documents. `docutils`_ supports adding new directives and roles via ``register_directive`` and ``register_role``.\n\nSphinx\n^^^^^^\nUnfortunately due to customizations in `Sphinx's parser`_ we cannot include all of its directives/roles (see `#29`_). However, we can include some of them as one-offs. Here is an example of adding a directive from `Sphinx`_.\n\n.. _`Sphinx`: http://sphinx-doc.org/\n.. _`Sphinx's parser`: Sphinx_\n.. _`#29`: https://github.com/twolfson/restructuredtext-lint/issues/29#issuecomment-243456787\n\nhttps://github.com/sphinx-doc/sphinx/blob/1.3/sphinx/directives/code.py\n\n**sphinx.rst**\n\n.. code:: rst\n\n Hello\n =====\n World\n\n .. highlight:: python\n\n Hello World!\n\n**sphinx.py**\n\n.. code:: python\n\n # Load in our dependencies\n from docutils.parsers.rst.directives import register_directive\n from sphinx.directives.code import Highlight\n import restructuredtext_lint\n\n # Load our new directive\n register_directive('highlight', Highlight)\n\n # Lint our README\n errors = restructuredtext_lint.lint_file('docs/sphinx/README.rst')\n print errors[0].message # Error in \"highlight\" directive: no content permitted.\n\nExamples\n--------\nHere is an example of all invalid properties\n\n.. code:: python\n\n rst = \"\"\"\n Some content.\n\n Hello World\n =======\n Some more content!\n \"\"\"\n errors = restructuredtext_lint.lint(rst, 'myfile.py')\n errors[0].line # 5\n errors[0].source # myfile.py\n errors[0].level # 2\n errors[0].type # WARNING\n errors[0].message # Title underline too short.\n errors[0].full_message # Title underline too short.\n #\n # Hello World\n # =======\n\nContributing\n------------\nIn lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Test via ``nosetests``.\n\nDonating\n--------\nSupport this project and `others by twolfson`_ via `donations`_.\n\nhttp://twolfson.com/support-me\n\n.. _`others by twolfson`: http://twolfson.com/projects\n.. _donations: http://twolfson.com/support-me\n\nUnlicense\n---------\nAs of Nov 22 2013, Todd Wolfson has released this repository and its contents to the public domain.\n\nIt has been released under the `UNLICENSE`_.\n\n.. _UNLICENSE: https://github.com/twolfson/restructuredtext-lint/blob/master/UNLICENSE\n\n\n",
"bugtrack_url": null,
"license": "UNLICENSE",
"summary": "reStructuredText linter",
"version": "1.4.0",
"project_urls": {
"Download": "https://github.com/twolfson/restructuredtext-lint/archive/master.zip",
"Homepage": "https://github.com/twolfson/restructuredtext-lint"
},
"split_keywords": [
"restructuredtext",
"restructured text",
"rest",
"rst",
"lint"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "489c6d8035cafa2d2d314f34e6cd9313a299de095b26e96f1c7312878f988eec",
"md5": "05aae776c7fe02edb03f3b2601ac6b67",
"sha256": "1b235c0c922341ab6c530390892eb9e92f90b9b75046063e047cacfb0f050c45"
},
"downloads": -1,
"filename": "restructuredtext_lint-1.4.0.tar.gz",
"has_sig": false,
"md5_digest": "05aae776c7fe02edb03f3b2601ac6b67",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16723,
"upload_time": "2022-02-24T05:51:10",
"upload_time_iso_8601": "2022-02-24T05:51:10.907416Z",
"url": "https://files.pythonhosted.org/packages/48/9c/6d8035cafa2d2d314f34e6cd9313a299de095b26e96f1c7312878f988eec/restructuredtext_lint-1.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-02-24 05:51:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "twolfson",
"github_project": "restructuredtext-lint",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "restructuredtext-lint"
}
JSON
