cookiecutter-autodocs#

Generate docs from a cookiecutter template. Pre-commit hook and github-action

Why?#

Cookiecutter is a powerful tool to create templates for all sorts of projects, but one of its downsides is it relies on a plain JSON file for its input (cookiecutter.json). Because JSON does not allow comments, you cannot document your inputs without writing the documentation separately.

cookiecutter-autodocs allows you to write your Cookiecutter’s input as a Toml file, cookiecutter.desc. In this file you can add defaults, info about the variable type, and a description of each variable.

An example cookiecutter.desc

[project_slug]
default = "new_project"
description = "The name of the project."
type = "string"

[python_version]
default = "3.11.2"
description = "What python version to use with this project"
type = "string"

[dev_requirements]
default = []
description = "What dev requirements does this project have"
type = "list(string)"

[author]
default = ""
description = "Who's the author?"
type = "string"

This would generate into the following cookiecutter.json

{
    "project_slug": "new_project",
    "python_version": "3.11.2",
    "dev_requirements": [],
    "author": ""
}

You can then use this cookiecutter.desc file to generate additional documentation, like a markdown table

cookiecutter-autodocs generate markdown -i cookiecutter.desc

name | description | default | type |required

project_slug

The name of the project.

new_project

string

False

python_version

What python version to use with this project

3.11.2

string

False

dev_requirements

What dev requirements does this project have

[]

list(string)

False

author | Who’s the author? | | string | True

Installation#

pip install cookiecutter-autodocs

Indices and tables#