restructuredtext-lint 1.2.2

CLI Utility

For your convenience, we present a CLI utility rst-lint (also available as restructuredtext-lint).

$ 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.

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)

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

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

Returns: Same structure as restructuredtext_lint.lint

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.

https://github.com/sphinx-doc/sphinx/blob/1.3/sphinx/directives/code.py

sphinx.rst

Hello
=====
World

.. highlight:: python

    Hello World!

sphinx.py

# 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.