Skip to main content

Generate docs from your cookiecutter template

Project description

cookiecutter-autodocs

Generate docs for a cookiecutter template's inputs. 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"

You can then generate a cookiecutter.json from this cookiecutter.desc file.

cookiecutter-autodocs generate cookiecutter -i cookiecutter.decs -o cookiecutter.json
cat cookiecutter.json
{
    "project_slug": "new_project",
    "python_version": "3.11.2",
    "dev_requirements": [],
    "author": ""
}

You can also use the 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

CLI

pip install cookiecutter-autodocs

Documentation

See ReadTheDocs for usage and more detailed documentation.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cookiecutter_autodocs-0.0.3.tar.gz (7.6 kB view hashes)

Uploaded Source

Built Distribution

cookiecutter_autodocs-0.0.3-py3-none-any.whl (10.6 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page