Metadata-Version: 2.1
Name: ansible-autodoc-fork
Version: 0.5.6
Summary: FORK - Generate documentation from annotated playbooks and roles using templates
Home-page: https://github.com/rennym19/ansible-autodoc
Author: Andres Bott
Author-email: contact@andresbott.com
License: UNKNOWN
Description: # ansible-autodoc
        
        [![CircleCI](https://circleci.com/gh/AndresBott/ansible-autodoc/tree/master.svg?style=svg)](https://circleci.com/gh/AndresBott/ansible-autodoc/tree/master)
        
        Generate documentation from annotated playbooks and roles using templates.
        
            Note: this project is currently in Beta, issues, ideas and pull requests are welcome.
        
        # Features
        * allow to document playbook projects and roles
        * use templates to generate and maintain the documentation
        * extended functions when documenting:
           * tags: the autodoc will search for used tags in the project
        
        # Getting started
        
        ```
        # install 
        pip install ansible-autodoc
        
        # print help 
        ansible-autodoc -h 
        
        # print parsed annotation results in the cli 
        ansible-autodoc -p all path/to/role_or_playbook 
        
        # generate README file based on annotations  
        ansible-autodoc [path/to/project] 
        ``` 
        
        notes: 
        * you can use [grip](https://pypi.org/project/grip/) to see the live changes.
        * this only runs with python 3, if you still have python 2.x use pip3
        
        
        # Annotations
        
        Use the following annotations in your playbooks and roles
        
        * __meta:__ use @meta to annotate the metadata of playbook or role, like author
        check below list of useful metadata
          * author: (self explanatory)
          * description: playbook / role description
          * name: to define a different role/project name instead of the folder name
          * license: (self explanatory)
          * email: (self explanatory)
          
        ```yaml
        # @meta author: Author Name
        # @meta description: Project description
        ```  
        * __todo:__ use @todo to annotate improvements, bugs etc
        ```yaml
        # @todo bug: bug description
        # @todo improvement: improvement 
        ```
        
        * __action:__ use @action to annotate a actions performed by the playbook/role
        ```yaml
        # @action install # this action describes the installation  
        # @action # this action does not have a section, only description 
        ```
        
        * __tags:__ use @tag to annotate tags, this is a special annotation as this will not only search for annotations,
        but also for used tags in the project and add that to the generated output.
        ```yaml
        # @tag tagname # tag description   
        ```
        
        
        * __variables:__ use @var this to annotate configuration variables
        ```yaml
        # @var my_var: default_value # description of the variable   
        ```
        
        * __example:__ the idea is that after every annotation, we can define an example block, linked to the annotation.
        in this case the example will be part of the var annotation.
        ```yaml
        # @var my_var: default_value # description of the variable   
        my_var: default_value
        # @example # the hash is needed due to the parser constrains
        # my_var:
        #  - subitem: string
        #  - subitem2: string
        # @end
        ``` 
        
        # Templates
        
        ansible-autodoc comes with 3 templates out of the box, the default is "readme", you can change this in configuration.
        
        If you want to create your own project specific templates, see the [template documentation](doc/templates.md)
        
        If a file already exists in the output, the you will be prompted to overwrite or abort.
        
        ### README
        
        The default "readme" template will generate a README.md file in the root of the project, detailing the sections:
        
        * title and description
        * actions
        * tags
        * variables
        * todos
        * license
        * author infomration
        
        you can extend this my creating a file `"_readme_doby.md"` in the root of your project, this will be included in the rendered Readme just after the 
        initial description.
        
        ### Doc and README
        
        The "doc_and_readme" template is an extended template intended to be used playbook projects with several roles, it will generate a minimal
        README.md file and a documentation subfolder "doc" with more detailed information.
        
        you can extend this my creating a file `"_readme_doby.md"` in the root of your project, this will be included in the rendered Readme just after the 
        initial description.
         
        the files created in the documentation folder will cover: 
        
        * tags: list all tags classified by roles
        * variables: list all variables classified by roles
        * todo: list all todo actions classified by roles
        * report: provides a report of the project and useful information during development
        
        you can extend the documentation in this folder, just keep in mind that generated files will be overwritten.
        
        
        ### Command line 
        
        The "cliprint" template is used to display the content when you use the command line print parameter "-p"
        
        
        ## Configuration
        you can create a configuration file "autodoc.config.yaml" in the root of your project in order to modify
        several behaviours, see the sample config file for more details:
        
        ```$xslt
        # role or project with playbooks
        $ cd <project> 
        
        # create sample configuration (optional) 
        # you can pass the options as parameters too
        $ ansible-autodoc --sample-doc > autodoc.config.yaml
        ```
        
        
Platform: UNKNOWN
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Documentation
Description-Content-Type: text/markdown
