pratidoc 0.1.0

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

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

Name	Enabled	Description
PRATIDOC0	True	File README should be defined.
PRATIDOC1	True	Only one README file should be defined.
PRATIDOC2	True	File SECURITY should be defined.
PRATIDOC3	True	Only one SECURITY file should be defined.
PRATIDOC4	True	File LICENSE should be defined.
PRATIDOC5	True	Only one LICENSE file should be defined.
PRATIDOC6	True	File CHANGELOG should be defined.
PRATIDOC7	True	Only one CHANGELOG file should be defined.
PRATIDOC8	True	File CITATION should be defined.
PRATIDOC9	True	Only one CITATION file should be defined.
PRATIDOC10	True	File DCO should be defined.
PRATIDOC11	True	Only one DCO file should be defined.
PRATIDOC12	True	File ADOPTERS should be defined.
PRATIDOC13	True	Only one ADOPTERS file should be defined.
PRATIDOC14	True	File CODE_OF_CONDUCT should be defined.
PRATIDOC15	True	Only one CODE_OF_CONDUCT file should be defined.
PRATIDOC16	True	File ROADMAP should be defined.
PRATIDOC17	True	Only one ROADMAP file should be defined.
PRATIDOC18	True	File CODEOWNERS should be defined.
PRATIDOC19	True	Only one CODEOWNERS file should be defined.
PRATIDOC20	True	File GOVERNANCE should be defined.
PRATIDOC21	True	Only one GOVERNANCE file should be defined.
PRATIDOC22	True	File CONTRIBUTING should be defined.
PRATIDOC23	True	Only one CONTRIBUTING file should be defined.
PRATIDOC24	True	File SUPPORT should be defined.
PRATIDOC25	True	Only one SUPPORT file should be defined.

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.