Package: restructuredtext-lint
reStructuredTextlinterThis was created out of frustration withPyPI; it sucks finding out yourreSTis invalidafteruploading it. It is being developed in junction with aSublime Textlinter.Getting StartedInstall the module with:pip install restructuredtext_lintimportrestructuredtext_linterrors=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 UtilityFor your convenience, we present a CLI utilityrst-lint(also available asrestructuredtext-lint).$rst-lint--helpusage: 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-lintREADME.rstWARNING README.rst:2 Title underline too short.Other toolsrestructuredtext-lintis also integrated in other tools. A list can be found and updated in our wikihttps://github.com/twolfson/restructuredtext-lint/wiki/Integration-in-other-toolsPyPI issuesWhile a document may lint cleanly locally, there can be issues when submitted it toPyPI. Here are some common problems:Usage of non-builtin lexers (e.g.bibtex) will pass locally but not be recognized/parsable onPyPIThis is due toPyPInot having a non-builtin lexer installedPlease avoid non-builtin lexers to avoid complicationsFor more information, see#27Relative 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 whitelistedhttp://stackoverflow.com/a/16594755Please use absolute hyperlinks (e.g.https://github.com/twolfson/restructuredtext-lint/blob/master/UNLICENSE)Documentationrestructuredtext-lintexposes alintandlint_filefunctionrestructuredtext_lint.lint(content, filepath=None, rst_prolog=None)LintreStructuredTextand return errorscontentString-reStructuredTextto be lintedfilepathString- Optional path to file, this will be returned as the sourcerst_prologString- Optional content to prepend to content, line numbers will be offset to ignore thisReturns:errorsList- List of errorsEach error is a class fromdocutilswith the following attrslineInteger|None- Line where the error occurredOn rare occasions, this will beNone(e.g. anonymous link mismatch)sourceString-filepathprovided in parameterslevelInteger- Level of the warningLevels represent ‘info’: 1, ‘warning’: 2, ‘error’: 3, ‘severe’: 4typeString- Noun describing the error levelLevels can be ‘INFO’, ‘WARNING’, ‘ERROR’, or ‘SEVERE’messageString- Error messagefull_messageString- Error message and source lines where the error occurredIt should be noted thatlevel,type,message, andfull_messageare custom attrs added onto the originalsystem_messagerestructuredtext_lint.lint_file(filepath, encoding=None, *args, **kwargs)Lint areStructuredTextfile and return errorsfilepathString- Path to file for lintingencodingString- Encoding to read file in asWhenNoneis provided, it will use OS default as provided bylocale.getpreferredencodingThe list of supported encodings can be found athttp://docs.python.org/2/library/codecs.html#standard-encodings*args- Additional arguments to be passed tolint**kwargs- Additional keyword arguments to be passed tolintReturns: Same structure asrestructuredtext_lint.lintExtensionUnder the hood, we leveragedocutilsfor parsing reStructuredText documents.docutilssupports adding new directives and roles viaregister_directiveandregister_role.SphinxUnfortunately due to customizations inSphinx’s parserwe 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 fromSphinx.https://github.com/sphinx-doc/sphinx/blob/1.3/sphinx/directives/code.pysphinx.rstHello=====World..highlight::pythonHello World!sphinx.py# Load in our dependenciesfromdocutils.parsers.rst.directivesimportregister_directivefromsphinx.directives.codeimportHighlightimportrestructuredtext_lint# Load our new directiveregister_directive('highlight',Highlight)# Lint our READMEerrors=restructuredtext_lint.lint_file('docs/sphinx/README.rst')printerrors[0].message# Error in "highlight" directive: no content permitted.ExamplesHere is an example of all invalid propertiesrst="""
Some content.

Hello World
=======
Some more content!
"""errors=restructuredtext_lint.lint(rst,'myfile.py')errors[0].line# 5errors[0].source# myfile.pyerrors[0].level# 2errors[0].type# WARNINGerrors[0].message# Title underline too short.errors[0].full_message# Title underline too short.## Hello World# =======ContributingIn lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Test vianosetests.DonatingSupport this project andothers by twolfsonviadonations.http://twolfson.com/support-meUnlicenseAs of Nov 22 2013, Todd Wolfson has released this repository and its contents to the public domain.It has been released under theUNLICENSE.