Skip to main content

Generate docs from your cookiecutter template

Project description

cookiecutter-autodocs

All Contributors

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.

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

Contributors

Thanks go to these wonderful people (emoji key):

Andrew
Andrew

🤔 💻 ⚠️ 📖

This project follows the all-contributors specification. Contributions of any kind welcome!

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-1.0.0.tar.gz (9.0 kB view details)

Uploaded Source

Built Distribution

cookiecutter_autodocs-1.0.0-py3-none-any.whl (11.4 kB view details)

Uploaded Python 3

File details

Details for the file cookiecutter_autodocs-1.0.0.tar.gz.

File metadata

  • Download URL: cookiecutter_autodocs-1.0.0.tar.gz
  • Upload date:
  • Size: 9.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/4.0.1 CPython/3.11.3

File hashes

Hashes for cookiecutter_autodocs-1.0.0.tar.gz
Algorithm Hash digest
SHA256 be160865105b53ef7a31cff1b2a623883167d478cb46e0d84990c087e6632bb0
MD5 94f1698a05b822f07c5668c91a79359d
BLAKE2b-256 f0842c0668efd73a601eb199e4e9bb9b8febca7b95da1c91786d2113eefc0e96

See more details on using hashes here.

File details

Details for the file cookiecutter_autodocs-1.0.0-py3-none-any.whl.

File metadata

File hashes

Hashes for cookiecutter_autodocs-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 30250b1235057555bdafa725ac8f5cbe63b6d8e20d3160e38d676a2f98f8c63f
MD5 14520b624a1728facb030db4fc65f20a
BLAKE2b-256 fac7a9685d11c19c8011147a0711af2c8907da8014c9e72d4a645b0d40ee3cae

See more details on using hashes here.

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