Skip to main content

reStructuredText linter

Project description

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.

Getting Started

Install the module with: pip install restructuredtext_lint

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

$ rst-lint --help
usage: rst-lint [-h] [--format FORMAT] [--encoding ENCODING] filepath [filepath ...]

Lint reStructuredText files

positional arguments:
  filepath         File to lint

optional arguments:
  -h, --help            show this help message and exit
  --format FORMAT       Format of output (e.g. text, json)
  --encoding ENCODING   Encoding of the source file (e.g. utf-8)

$ rst-lint README.rst
WARNING README.rst:2 Title underline too short.

Documentation

restructuredtext-lint exposes a lint and lint_file function

restructuredtext_lint.lint(content, filepath=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

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)

Lint a reStructuredText file and return errors

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

Examples

Here is an example of all invalid properties

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

Support via Gittip

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

restructuredtext_lint-0.13.0.zip (32.8 kB view details)

Uploaded Source

restructuredtext_lint-0.13.0.tar.gz (18.9 kB view details)

Uploaded Source

File details

Details for the file restructuredtext_lint-0.13.0.zip.

File metadata

File hashes

Hashes for restructuredtext_lint-0.13.0.zip
Algorithm Hash digest
SHA256 0c731bc054006434dad1e6a912297674b0892e90a24494bb4d869f9eeeeae31a
MD5 c34caf5bc176681f06cd486c72bfb6ac
BLAKE2b-256 24ec50320b5341910dc0d914ca491e7075f9c470cce81c6f1a0b4af289478abc

See more details on using hashes here.

Provenance

File details

Details for the file restructuredtext_lint-0.13.0.tar.gz.

File metadata

File hashes

Hashes for restructuredtext_lint-0.13.0.tar.gz
Algorithm Hash digest
SHA256 d46c744b7bfdaad5e4d9ddb54d2ceea1f123236cb37c96d8623b7a92854f9d43
MD5 9d04ad0b8cb55cbf51606148674769f7
BLAKE2b-256 e6f734b0ba06a961f721934f59c766c7ac6d62b3bec16d1c92b1882da199b660

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page