https://github.com/allenrobel/doc-builder-ansible-dcnm

https://github.com/allenrobel/doc-builder-ansible-dcnm

Last synced: 16 days ago
JSON representation

• Host: GitHub
• URL: https://github.com/allenrobel/doc-builder-ansible-dcnm
• Owner: allenrobel
• Created: 2024-11-08T19:51:52.000Z (about 2 months ago)
• Default Branch: main
• Last Pushed: 2024-11-19T19:41:02.000Z (about 2 months ago)
• Last Synced: 2024-12-15T09:05:37.931Z (19 days ago)
• Language: Python
• Size: 163 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# Documentation builder for ansible-dcnm modules

This repo contains scripts to convert the DOCUMENTATION section of

Ansible module scripts (consisting of YAML) to Markdown format

amenable for display with Material for Mkdocs.

## Layout

### build_docs.bash

build_docs.bash does the following.

1. Executes `doc_getter.py` which (for each module)

    - Retrieves the module code from the ansible-dcnm repository

    - Saves the DOCUMENTATION docstring into ./documentation

    - Saves the EXAMPLES docstring into ./examples

    - Saves the RETURN docstring into ./return

2. Executes `doc_builder.py` which (for each module)

    -   Converts the DOCUMENTATION for the module

        (in ./documentation) to the markdown files in `./docs`.

    -   Appends the EXAMPLES docstring for the module

        (in ./examples) to the markdown file in `./docs`.

    -   Appends the RETURN docstring (if any) for the module

        (in ./return) to the markdown file in `./docs`.

### commit_docs.bash

Copies the markdown files in `./docs` to a separate repo

linked to allenrobel.github.io where the documentation

lives online.

### doc_getter.py

Retrieves the module files and parses out the DOCUMENTATION

and EXAMPLES sections.

### doc_builder.py

This does the actual conversion.

### docs

Contains the markdown generated by `build_docs.bash`.

### documentation

Contains YAML extracted from the DOCUMENTATION section of the

Ansible module scripts located at:

[Modules](https://github.com/CiscoDevNet/ansible-dcnm/tree/develop/plugins/modules)

### examples

Contains YAML extracted from the EXAMPLES section of the 

Ansible module scripts located at:

[Modules](https://github.com/CiscoDevNet/ansible-dcnm/tree/develop/plugins/modules)

### return

Contains YAML extracted from the RETURN section of the 

Ansible module scripts located at:

[Modules](https://github.com/CiscoDevNet/ansible-dcnm/tree/develop/plugins/modules)

### ut

See ut/README.md 

## Building the docs

``` bash

./build_docs.bash

./commit_docs.bash

```