rstcheck

https://rstcheck.readthedocs.io/en/latest/
Admin
A CLI application for checking the syntax of reStructuredText and code blocks nested within it.
Tokens:11,605
Snippets:257
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install pre-commit

Source: https://rstcheck.readthedocs.io/en/latest/_sources/installation.rst.txt

Install the pre-commit tool.

```console
pip install pre-commit
```

--------------------------------

### Install from PyPI

Source: https://rstcheck.readthedocs.io/en/latest/installation

You can simply install the package from PyPI.

```bash
$ pip install rstcheck

```

--------------------------------

### Install with Extras

Source: https://rstcheck.readthedocs.io/en/latest/installation

To install an extra simply add it in brackets.

```bash
$ pip install rstcheck[sphinx,toml]

```

--------------------------------

### Install Sphinx support

Source: https://rstcheck.readthedocs.io/en/latest/_sources/migrations.rst.txt

Instructions on how to install Sphinx support for rstcheck, either directly or via extras.

```bash
$ pip install sphinx  # directly

   $ pip install rstcheck[sphinx]  # or via extra
```

--------------------------------

### Install rstcheck from local clone

Source: https://rstcheck.readthedocs.io/en/latest/_sources/installation.rst.txt

Install rstcheck directly from a Git repository clone by cloning the repository and installing from the local clone.

```console
git clone https://github.com/rstcheck/rstcheck.git
cd rstcheck
pip install .
```

--------------------------------

### Install from local clone

Source: https://rstcheck.readthedocs.io/en/latest/installation

Install rstcheck directly from a Git repository clone by cloning the repository and installing from the local clone.

```bash
$ git clone https://github.com/rstcheck/rstcheck.git
$ cd rstcheck
$ pip install .

```

--------------------------------

### Install rstcheck with extras

Source: https://rstcheck.readthedocs.io/en/latest/_sources/installation.rst.txt

To install an extra functionality, add it in brackets like so.

```console
pip install rstcheck[sphinx,toml]
```

--------------------------------

### Install Sphinx support

Source: https://rstcheck.readthedocs.io/en/latest/migrations

Instructions on how to install Sphinx support for rstcheck, either directly or via extras.

```bash
$ pip install sphinx  # directly

$ pip install rstcheck[sphinx]  # or via extra

```

--------------------------------

### TOML Format Example

Source: https://rstcheck.readthedocs.io/en/latest/_sources/usage/config.rst.txt

An example of rstcheck configuration in the TOML format, demonstrating equivalent settings to the INI example.

```toml
[tool.rstcheck]
report_level = "WARNING"
ignore_directives = [
    "one",
    "two",
    "three",
]
ignore_roles = ["src", "RFC"]
ignore_substitutions = [
    "image_link"
]
ignore_languages = [
    "python",
    "cpp"
]
ignore_messages = "(Document or section may not begin with a transition\.$)"
```

--------------------------------

### Install pre-commit

Source: https://rstcheck.readthedocs.io/en/latest/installation

Install pre-commit to use rstcheck in a Git pre-commit hook.

```bash
pip install pre-commit

```

--------------------------------

### Install directly via git

Source: https://rstcheck.readthedocs.io/en/latest/installation

Install rstcheck directly via git.

```bash
$ pip install git+https://github.com/rstcheck/rstcheck

```

--------------------------------

### Add to .pre-commit-config.yaml

Source: https://rstcheck.readthedocs.io/en/latest/installation

Add rstcheck to your .pre-commit-config.yaml file.

```yaml
- repo: https://github.com/rstcheck/rstcheck
  rev: main # should be replaced with the current verison
  hooks:
    - id: rstcheck
      additional_dependencies: ['rstcheck[sphinx,toml]']

```

--------------------------------

### Install rstcheck directly via git

Source: https://rstcheck.readthedocs.io/en/latest/_sources/installation.rst.txt

Install rstcheck directly via git.

```console
pip install git+https://github.com/rstcheck/rstcheck
```

--------------------------------

### INI Format Example

Source: https://rstcheck.readthedocs.io/en/latest/_sources/usage/config.rst.txt

An example of rstcheck configuration in the INI format, showing various settings.

```ini
[rstcheck]
report_level=WARNING
ignore_directives =
    one,
    two,
    three,
ignore_roles=src, RFC
ignore_substitutions=
    image_link
ignore_languages=
    python,
    cpp
ignore_messages=(Document or section may not begin with a transition\.$)
```

--------------------------------

### Install rstcheck from PyPI

Source: https://rstcheck.readthedocs.io/en/latest/_sources/installation.rst.txt

You can simply install the package from PyPI using pip.

```console
pip install rstcheck
```

--------------------------------

### Inline Comments Example

Source: https://rstcheck.readthedocs.io/en/latest/_sources/usage/config.rst.txt

An example demonstrating the use of both flow control instructions and simple inline configuration comments.

```rst
.. rstcheck: ignore-next-code-block
.. code-block:: python

    print("Hello World")

.. rstcheck: ignore-languages=python
```

--------------------------------

### TOML format configuration example

Source: https://rstcheck.readthedocs.io/en/latest/usage/config

An example of rstcheck configuration in TOML format, using the [tool.rstcheck] section for settings like report_level, ignore_directives, ignore_roles, ignore_substitutions, ignore_languages, and ignore_messages.

```toml
[tool.rstcheck]
report_level = "WARNING"
ignore_directives = [
    "one",
    "two",
    "three",
]
ignore_roles = ["src", "RFC"]
ignore_substitutions = [
    "image_link"
]
ignore_languages = [
    "python",
    "cpp"
]
ignore_messages = "(Document or section may not begin with a transition\.$)"

```

--------------------------------

### INI format configuration example

Source: https://rstcheck.readthedocs.io/en/latest/usage/config

An example of rstcheck configuration in INI format, showing various settings like report_level, ignore_directives, ignore_roles, ignore_substitutions, ignore_languages, and ignore_messages.

```ini
[rstcheck]
report_level=WARNING
ignore_directives =
    one,
    two,
    three,
ignore_roles=src, RFC
ignore_substitutions=
    image_link
ignore_languages=
    python,
    cpp
ignore_messages=(Document or section may not begin with a transition\.$)

```

--------------------------------

### Skipping code blocks example

Source: https://rstcheck.readthedocs.io/en/latest/_sources/usage/config.rst.txt

Demonstrates how to use the 'ignore-next-code-block' instruction to skip a specific code block.

```rst
.. code-block:: rst

    .. rstcheck: ignore-next-code-block
    .. code-block:: python

        print("Hello world")
```

--------------------------------

### Add rstcheck to .pre-commit-config.yaml

Source: https://rstcheck.readthedocs.io/en/latest/_sources/installation.rst.txt

Add the rstcheck configuration to your .pre-commit-config.yaml file.

```yaml
- repo: https://github.com/rstcheck/rstcheck
  rev: main # should be replaced with the current verison
  hooks:
    - id: rstcheck
      additional_dependencies: ['rstcheck[sphinx,toml]']
```

--------------------------------

### Install Development Dependencies

Source: https://rstcheck.readthedocs.io/en/latest/_sources/workflows/development.rst.txt

Command to install rstcheck and its development dependencies into a virtual environment.

```bash
pip install -e .[dev]
```

--------------------------------

### Only inline comments example

Source: https://rstcheck.readthedocs.io/en/latest/_sources/usage/config.rst.txt

Illustrates ignoring code blocks using both inline comments and configuration file settings.

```rst
Example
=======

.. rstcheck: ignore-next-code-block
.. code-block:: python

    print("Here is an error."

.. rstcheck: ignore-languages=python
```

--------------------------------

### Inline comment example with flow control and config

Source: https://rstcheck.readthedocs.io/en/latest/usage/config

Demonstrates the use of 'ignore-next-code-block' for flow control and 'ignore-languages=python' for configuration within inline rst comments.

```rst
.. rstcheck: ignore-next-code-block
.. code-block:: python

    print("Hello World")

.. rstcheck: ignore-languages=python

```

--------------------------------

### Run Pre-commit Command

Source: https://rstcheck.readthedocs.io/en/latest/_sources/workflows/development.rst.txt

Example of running a specific pre-commit command within a tox environment.

```bash
tox -e pre-commit -- autoupdate --freeze
```

--------------------------------

### Check Sphinx support activation

Source: https://rstcheck.readthedocs.io/en/latest/_sources/migrations.rst.txt

Command to verify if Sphinx support is active in rstcheck.

```bash
$ rstcheck --help | grep Sphinx
```

--------------------------------

### Skipping code blocks example

Source: https://rstcheck.readthedocs.io/en/latest/usage/config

Demonstrates how to use the `ignore-next-code-block` flow control instruction to skip a single code block.

```rst
.. rstcheck: ignore-next-code-block
.. code-block:: python

    print("Hello world")

```

--------------------------------

### Run prep_release.py script

Source: https://rstcheck.readthedocs.io/en/latest/_sources/workflows/releases.rst.txt

This script is used to bump the version, finalize CHANGELOG.md, commit changes, and create a new git tag. The TYPE can be 'patch', 'minor', or 'major'.

```console
python3 prep_release.py <TYPE>
```

--------------------------------

### Run All Tests with Tox

Source: https://rstcheck.readthedocs.io/en/latest/workflows/development

Executes all available tests, linters, and formatters using tox.

```bash
$ tox

```

--------------------------------

### Run All Pre-commit Hooks

Source: https://rstcheck.readthedocs.io/en/latest/_sources/workflows/development.rst.txt

Command to execute all pre-commit hooks against the codebase using a tox environment.

```bash
tox -e pre-commit-run -- black
```

--------------------------------

### Check Sphinx support activation

Source: https://rstcheck.readthedocs.io/en/latest/migrations

Command to verify if Sphinx support is active in rstcheck.

```bash
$ rstcheck --help | grep Sphinx

```

--------------------------------

### Build sdist and wheel

Source: https://rstcheck.readthedocs.io/en/latest/_sources/workflows/releases.rst.txt

Command to build the source distribution (sdist) and wheel package.

```console
python -m build
```

--------------------------------

### Build sdist and wheel

Source: https://rstcheck.readthedocs.io/en/latest/workflows/releases

Command to build the source distribution (sdist) and wheel package.

```bash
$ python -m build
```

--------------------------------

### Project License

Source: https://rstcheck.readthedocs.io/en/latest/license

The MIT-like license under which the project is distributed.

```text
Copyright (C) 2013-2022 Steven Myint

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

```

--------------------------------

### Run All Tests with Tox

Source: https://rstcheck.readthedocs.io/en/latest/_sources/workflows/development.rst.txt

Command to execute all automated tests, linters, formatters, and coverage reports using tox.

```bash
$ tox
```

--------------------------------

### Publish package

Source: https://rstcheck.readthedocs.io/en/latest/_sources/workflows/releases.rst.txt

Command to upload the built package to a package repository.

```console
twine upload dist/*
```

--------------------------------

### Prepare Release Script

Source: https://rstcheck.readthedocs.io/en/latest/workflows/releases

Script to bump version, finalize CHANGELOG.md, commit changes, and create a new git tag. The TYPE can be 'patch', 'minor', or 'major'.

```bash
$ python3 prep_release.py <TYPE>
```

--------------------------------

### Use as a pre-commit hook

Source: https://rstcheck.readthedocs.io/en/latest/_sources/usage/integration.rst.txt

Configuration for pre-commit hook to use rstcheck.

```yaml
-   repo: https://github.com/rstcheck/rstcheck
    rev: ''  # Use the sha / tag you want to point at
    hooks:
    -   id: rstcheck
        additional_dependencies: []  # can be omitted if empty
```

--------------------------------

### Publish Package

Source: https://rstcheck.readthedocs.io/en/latest/workflows/releases

Command to upload the built package to the distribution index.

```bash
$ twine upload dist/*
```

--------------------------------

### Usage in Vim with Syntastic

Source: https://rstcheck.readthedocs.io/en/latest/_sources/usage/integration.rst.txt

Configuration for Syntastic to use rstcheck as a checker.

```vim
let g:syntastic_rst_checkers = ['rstcheck']
```

--------------------------------

### Push commit and tag to GitHub

Source: https://rstcheck.readthedocs.io/en/latest/_sources/workflows/releases.rst.txt

Command to push the latest commit and associated tags to GitHub.

```console
git push --follow-tags
```

--------------------------------

### Run Specific Tox Environment

Source: https://rstcheck.readthedocs.io/en/latest/_sources/workflows/development.rst.txt

Command to select and run a specific tox environment, such as 'pre-commit' or 'pre-commit-run'.

```bash
tox -m <ENVLIST>
```

--------------------------------

### rstcheck CLI

Source: https://rstcheck.readthedocs.io/en/latest/usage/cli

CLI of rstcheck. Enabled features: [‘Sphinx’]. Pass one or more RST FILES to check. Can be files or directories if –recursive is passed too. Pass “-” if you want to read from stdin.

```bash
rstcheck [OPTIONS] FILES...
```

--------------------------------

### Push Commit and Tag

Source: https://rstcheck.readthedocs.io/en/latest/workflows/releases

Command to push the commit and tag to the remote repository.

```bash
$ git push --follow-tags
```
Tokens:
Raw