Cookiecutter-docs

cookiecutter-docs is inspired from terraform-docs to autogenerate the documentation from cookiecutter.json to a markdown file.

As for now, cookiecutter does not support YAML on his configuration file (only JSON).

To simulate the ability to add a description to each input variable, we use a workaround only available in cookiecutter > 2.x:

Here is an example of a cookiecutter.json file:

{
  "input1": "value1",
  "input2": "value2",
  "input3": "value3",

  "_DOC_input1": "description1",
  "_DOC_input2": "description2",
  "_DOC_input3": "description3"
}

And here is an example of a README.md file:

...

## Documentation
<!-- BEGIN_COOKIECUTTER_DOCS -->
<!-- END_COOKIECUTTER_DOCS -->

...

Installation

Require Python >= 3.8

Remote (recommended)

From private repository.

pip install -U git+ssh://git@git.sk5.io/skale-5/docker-images/cookiecutter-docs.git@vX.Y.Z

From public repository.

pip install -U git+https://github.com/skale-5/cookiecutter-docs.git@vX.Y.Z

Available flags

Flag	Description	Default
--version	Show version	N/A
--input-file	JSON file to configure cookiecutter	cookiecutter.json
--output-file	Markdown file to inject documentation	README.md
--anchor-start	Beginning line where the mardown is injected	<!-- BEGIN_COOKIECUTTER_DOCS -->
--anchor-stop	Ending line where the mardown is injected	<!-- END_COOKIECUTTER_DOCS -->
--strict	Returns an error if the JSON file is not well documented	False
--only-verify	Do not override the file, only compare it	False

Usage

CLI

cookiecutter-docs --input-file cookiecutter.json --output-file README.md

Docker

docker run --rm -it -v $(pwd):/data skale5/cookiecutter-docs --input-file data/cookiecutter.json --output-file data/README.md

Pre-commits

repos:
  - repo: git@git.sk5.io:skale-5/docker-images/cookiecutter-docs.git
    rev: v1.0.1
    hooks:
      - id: cookiecutter-docs

CI

cookiecutter-docs:
  stage: quality
  image:
    name: "skale5/cookiecutter-docs:1.O.1"
    entrypoint: [""]
  script:
    - cookiecutter-docs --only-verify --strict