pratidoc

Lint your repository docs - ensure the essentials are always there.

✨ Features 🚀 Quick start 📚 Documentation 🤝 Contribute 👍 Adopters 📜 Legal

Features

pratidoc is a documentation checker which verifies if your project contains a set of essential documentation files:

• Well-defined files: Only the files common in large open source projects are searched for.
• Comprehensive choice: Documents from a wide range of categories (like legal, governance, security, community, etc.) are included.
• Link to source: Wherever applicable each rule points to the official/well-respected resource with more information regarding it.

Table of contents

• Quick start
  • Installation
  • Usage
• Advanced
  • Configuration
  • Run as a pre-commit hook
  • Rules

Quick start

Installation

[!TIP] You can use your favorite package manager like uv, hatch or pdm instead of pip.

> pip install pratidoc

Usage

To check against the rules run the following from the command line:

> pratidoc check

[!NOTE] The command should be ran from the directory which we want to verify and no path(s) should be passed as arguments!

an example output could be:

> ALL:-:-: PRATIDOC1 Multiple README files exist.

[!NOTE] This is a repo-wide linter, therefore it will not point to a specific line, instead ALL:-:-: means that the rule was violated in current working directory.

Advanced

Configuration

You can configure pratidoc in pyproject.toml (or .pratidoc.toml in the root of your project, just remove the [tool.pratidoc] section), for example:

[tool.pratidoc]
# include rules by their code
include_codes = [1, 2, 5] # default: all rules included
# exclude rules by their code (takes precedence over include)
exclude_codes = [4, 5, 6] # default: no rules excluded
# whether to exit after first error or all errors
end_mode = "first" # default: "all"

[!WARNING] You can only disable rules via include/exclude codes as shown above.

Run as a pre-commit hook

pratidoc can be used as a pre-commit hook, to add as a plugin:

repos:
-   repo: "https://github.com/open-nudge/pratidoc"
    rev: ...  # select the tag or revision you want, or run `pre-commit autoupdate`
    hooks:
    -   id: "pratidoc"

Rules

[!TIP] Run pratidoc rules to see the list of available rules.

pratidoc provides the following rules (links omitted for brevity):

You can consult the following resources to learn more about a given document (click on the name to go to the resource):

• README
• SECURITY
• LICENSE
• CHANGELOG
• CITATION
• DCO
• CODE_OF_CONDUCT
• SUPPORT
• CONTRIBUTING
• CODEOWNERS

Contribute

We welcome your contributions! Start here:

• Code of Conduct
• Contributing Guide
• Roadmap
• Changelog
• Report security vulnerabilities
• Open an Issue

Legal

• This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
• This project is copyrighted by open-nudge - the appropriate copyright notice is included in each file.