Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/andrewthetechie/cookiecutter-autodocs
Generate docs for a cookiecutter template's inputs. Pre-commit hook and github-action
https://github.com/andrewthetechie/cookiecutter-autodocs
Last synced: about 1 month ago
JSON representation
Generate docs for a cookiecutter template's inputs. Pre-commit hook and github-action
- Host: GitHub
- URL: https://github.com/andrewthetechie/cookiecutter-autodocs
- Owner: andrewthetechie
- License: mit
- Created: 2023-05-06T19:04:16.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-04-30T14:36:37.000Z (8 months ago)
- Last Synced: 2024-05-04T00:25:25.049Z (8 months ago)
- Language: Python
- Size: 252 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# cookiecutter-autodocs
[](#contributors-)
Generate docs for a cookiecutter template's inputs. Pre-commit hook and github-action
## Why?
[Cookiecutter](https://cookiecutter.readthedocs.io/en/stable/) 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
```toml
[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.
```shell
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:
```shell
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
```shell
pip install cookiecutter-autodocs
```
## Documentation
See [ReadTheDocs](https://cookiecutter-autodocs.readthedocs.io/en/latest/) for usage and more detailed documentation.
## Contributing
Contributions are very welcome.
To learn more, see the [Contributor Guide](./CONTRIBUTING.md).
### Contributors
Thanks go to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
