{"id":1698,"library":"restructuredtext-lint","title":"reStructuredText Linter","description":"restructuredtext-lint is a Python library for linting reStructuredText (RST) documents to identify errors, warnings, and style issues. It leverages `docutils` for parsing and provides programmatic access to linting results, including line numbers, types, and messages. The current version is 2.0.2, and it maintains a slow but active release cadence, primarily focusing on bug fixes and compatibility with newer Python and `docutils` versions.","status":"active","version":"2.0.2","language":"en","source_language":"en","source_url":"https://github.com/twolfson/restructuredtext-lint","tags":["linter","restructuredtext","rst","code-quality","docutils"],"install":[{"cmd":"pip install restructuredtext-lint","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for parsing reStructuredText documents.","package":"docutils","optional":false}],"imports":[{"symbol":"lint","correct":"from restructuredtext_lint import lint"},{"note":"The import path for `lint_file` changed in version 2.0.0. It was moved from the top-level `lint` module to `file_lint`.","wrong":"from restructuredtext_lint.lint import lint_file","symbol":"lint_file","correct":"from restructuredtext_lint.file_lint import lint_file"}],"quickstart":{"code":"from restructuredtext_lint import lint\n\nrst_content = '''\nMy Document\n===========\n\n.. This is a comment\n\nThis is a paragraph with some `broken\n\n.. bad_directive::\n\nAn error will be reported above.\n'''\n\nerrors = lint(rst_content)\n\nif errors:\n    print(f\"Found {len(errors)} linting issues:\")\n    for error in errors:\n        print(f\"  [{error.type.upper()}] Line {error.line}: {error.message}\")\nelse:\n    print(\"No linting issues found.\")\n\n# To lint a file:\n# from restructuredtext_lint.file_lint import lint_file\n# errors_from_file = lint_file('path/to/your/file.rst')","lang":"python","description":"This quickstart demonstrates how to use `restructuredtext-lint` to check a string for reStructuredText syntax errors and warnings. It iterates through the detected errors, printing their type, line number, and message. It also shows the general approach for linting files."},"warnings":[{"fix":"Update your import statements: change `from restructuredtext_lint.lint import lint_file` to `from restructuredtext_lint.file_lint import lint_file`.","message":"The import path for `lint_file` changed significantly in version 2.0.0, moving from the main `lint` module to a dedicated `file_lint` module.","severity":"breaking","affected_versions":"2.0.0 and later"},{"fix":"Ensure your environment is running Python 3. For projects still requiring Python 2, you must pin the dependency to `restructuredtext-lint<2.0.0`.","message":"Version 2.x and above of `restructuredtext-lint` are exclusively Python 3 compatible. Earlier 1.x versions supported Python 2.","severity":"breaking","affected_versions":"2.0.0 and later"},{"fix":"When processing the list of `errors`, inspect the `error.type` attribute to filter or categorize issues according to your requirements. For example, `if error.type == 'error': ...`.","message":"Linting results (errors) can have different severity `type` values, including 'info', 'warning', 'error', and 'severe'. Consumers of the library must handle these distinctions if they wish to filter or prioritize issues.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If relying on `lint_file` and specific Sphinx extensions or features, be aware that 2.0.0 was the only version in the 2.x series to explicitly support a Sphinx backend; subsequent versions reverted to `docutils`. Test thoroughly when upgrading through these specific point releases.","message":"In version 2.0.0, `lint_file` briefly switched its parsing backend from `docutils` to `sphinx`. This was reverted in 2.0.1, restoring `docutils` as the backend. This might cause subtle behavioral differences or break Sphinx-specific directives if upgrading *only* to 2.0.0, then later upgrading to 2.0.1+.","severity":"gotcha","affected_versions":"2.0.0, 2.0.1 and later"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}