Documentation: Line Length and Wrapping

[trickeydan]

there's some variation in line wrapping between files – do you have opinions on whether we should hard-wrap docs or not (and if so, at how many columns)? it's already inconsistent in the existing docs, so don't worry about changing anything this pr, but possibly something to consider

I'm not really sure where I sit on this. I'll open an issue and we can discuss this evening.

Originally posted by @trickeydan in #20 (comment)

[trickeydan]

I began work on a linter based on rst-lint for this, but ran into issues with the Sphinx parser and custom directives.

Adding my code here for future reference so it doesn't get lost

#!/usr/bin/env python3
"""
Lint the documentation.

Makes use of restructuredtext_lint, but must be a custom script to allow for
custom directives that Sphinx uses.
"""
from enum import Enum
from pathlib import Path
from typing import NamedTuple, Optional, Set

import click
from docutils.parsers.rst.directives import register_directive
from m2r2 import MdInclude
from sphinx.directives.code import Highlight
import restructuredtext_lint

# Load non-standard Sphinx directives
register_directive('highlight', Highlight)
register_directive('mdinclude', MdInclude)


class ProblemLevel(Enum):
    """Level of a lint problem."""

    ERROR = "ERROR"
    WARNING = "WARNING"
    INFO = "INFO"

class LintProblem(NamedTuple):
    """Information about a problem found when linting."""

    file_path: Path
    level: ProblemLevel
    line_number: Optional[int]
    description: str


@click.command("lint-docs")
@click.argument("path", type=click.Path())
def main(path: str) -> None:
    """Lint documentation."""
    problems: Set[LintProblem] = set()
    rst_files = Path(path).rglob("*.rst")
    for file_path in rst_files:
        problems |= rst_lint(file_path)
    
    for p in problems:
        click.secho(f"{p.file_path}:{p.line_number} {p.description}")

def rst_lint(file_path: Path) -> Set[LintProblem]:
    problems: Set[LintProblem] = set()
    errors = restructuredtext_lint.lint_file(file_path)
    for error in errors:
        level_map = {
            1: ProblemLevel.INFO,
            2: ProblemLevel.WARNING,
            3: ProblemLevel.ERROR,
            4: ProblemLevel.ERROR,
        }
        problems.add(
            LintProblem(
                file_path=file_path,
                level=level_map[error.level],
                line_number=error.line,
                description=error.message.replace("\n", " "),
            )
        )
    return problems

if __name__ == "__main__":
    main()