ansidocs

Name	ansidocs JSON
Version	1.0.8 JSON
	download
home_page
Summary	Generate and collate documentation for Ansible projects
upload_time	2022-12-21 18:41:07
maintainer
docs_url	None
author
requires_python	>=3.8
license	Copyright (c) 2018 The Python Packaging Authority Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
keywords	ansible documentation generator generate
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

# ansidocs

Ansidocs is a command line tool designed to help collate and generate documentation for your Ansible project.

See the `example_projects` folder in this repo for examples of the READMEs generated by this tool.

## Usage

After installing the pip package, a command line utility should be available in your virtual environment.

To see available options and the help message, simply run:
``` bash
ansidocs
# or
ansidocs -h
```

To generate documentation for a project in directory `/my/project`:
``` bash
ansidocs gen -d '/my/project'
```

## Configuration

Ansidocs comes with support for the common Ansible project layouts: roles and collections. You can modify how these projects are processed 
or create your own project layout by modifying the configuration files.

By default, config files are located in your user directory at `~/.ansidocs`. Files are placed here once the program is run, or by running 
the config generation command:
```bash
ansidocs config
```

You can forcefully remove this directory and recreate it by using the refresh flag:
```bash
ansidocs config -r
```

### Customizing Project Layouts and READMEs

Its possbile to customize or create your own project layout, as well as modify the existing templates used for README generation.

#### Project Layouts

A project layout is a configuration entry that describes where different pieces of your project exist relative to the root directory. 
Although the types of project parts are limitted to what the program supports, you can add, remove, or move the project parts. 
To do this, modify the existing configuration file (by default at `~/.ansidocs/ansidocs.yml`). In that file, there is a dictionary 
called `project_layouts`.

Note: The meta file attribute is used to link a project layout to your project. So, no layouts should have the same meta file 
value, and the meta file must exist in your project for the program to recognize its layout.

An example of the project layout struct can be found in your configuration file.

#### Customizing README Templates

Each project layout has the option to define a custom README template and add, remove, or reformat data. The templates are found in your 
configuration directory, (by default at `~/.ansidocs/templates`). If the program finds a folder with the same name as your layout, it will 
look in that directory for templates before falling back to the `defaults` directory.

When a project's README is rendered, it occurs in 4 stages:
1. render description.md.j2
2. render usage.md.j2
3. render footer.md.j2
4. Compile those renderings as variables, and use them to render README.md.j2

#### Special Documentation Files

If your project layout defines a `docs` attribute and that directory exists, ansidocs will look in that directory for certain files and include them in the README generation. 
Some supported documents include:

usage.md - This file will be injected at the top of the `Usage` section in your README.md. The file should be pure markdown, there will be no templating or substitution done on this file.

description.md - This file will be injected at the top of the `Description` section in your README.md. The file should be pure markdown, there will be no templating or substitution done on this file.

defaults.yml - This file should contain descriptions for defaults defined in your project, if any. This file is YAML and should match the keys in your `defaults/main.yml` or corresponding defaults file. Values should be strings that are used as descriptions when compiling the defaults markdown table

Raw data

            {
    "_id": null,
    "home_page": "",
    "name": "ansidocs",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": "",
    "keywords": "ansible,documentation,generator,generate",
    "author": "",
    "author_email": "Mike Morency <mikemorency93@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/92/26/f8908fd25c74b28ef89f9d198e9bfd4d6cf7cf799ebbe6931f7722efa7cf/ansidocs-1.0.8.tar.gz",
    "platform": null,
    "description": "# ansidocs\n\nAnsidocs is a command line tool designed to help collate and generate documentation for your Ansible project. <br>\n\nSee the `example_projects` folder in this repo for examples of the READMEs generated by this tool.\n\n## Usage\n\nAfter installing the pip package, a command line utility should be available in your virtual environment.\n\nTo see available options and the help message, simply run:\n``` bash\nansidocs\n# or\nansidocs -h\n```\n\nTo generate documentation for a project in directory `/my/project`:\n``` bash\nansidocs gen -d '/my/project'\n```\n\n## Configuration\n\nAnsidocs comes with support for the common Ansible project layouts: roles and collections. You can modify how these projects are processed <br>\nor create your own project layout by modifying the configuration files.\n\nBy default, config files are located in your user directory at `~/.ansidocs`. Files are placed here once the program is run, or by running <br>\nthe config generation command:\n```bash\nansidocs config\n```\n\nYou can forcefully remove this directory and recreate it by using the refresh flag:\n```bash\nansidocs config -r\n```\n\n### Customizing Project Layouts and READMEs\n\nIts possbile to customize or create your own project layout, as well as modify the existing templates used for README generation.\n\n#### Project Layouts\n\nA project layout is a configuration entry that describes where different pieces of your project exist relative to the root directory. <br>\nAlthough the types of project parts are limitted to what the program supports, you can add, remove, or move the project parts. <br>\nTo do this, modify the existing configuration file (by default at `~/.ansidocs/ansidocs.yml`). In that file, there is a dictionary <br>\ncalled `project_layouts`. <br>\n\n<b>Note:</b> The meta file attribute is used to link a project layout to your project. So, no layouts should have the same meta file <br>\nvalue, and the meta file must exist in your project for the program to recognize its layout.\n\nAn example of the project layout struct can be found in your configuration file.\n\n#### Customizing README Templates\n\nEach project layout has the option to define a custom README template and add, remove, or reformat data. The templates are found in your <br>\nconfiguration directory, (by default at `~/.ansidocs/templates`). If the program finds a folder with the same name as your layout, it will <br>\nlook in that directory for templates before falling back to the `defaults` directory.\n\nWhen a project's README is rendered, it occurs in 4 stages:\n1. render description.md.j2\n2. render usage.md.j2\n3. render footer.md.j2\n4. Compile those renderings as variables, and use them to render README.md.j2\n\n#### Special Documentation Files\n\nIf your project layout defines a `docs` attribute and that directory exists, ansidocs will look in that directory for certain files and include them in the README generation. <br>\nSome supported documents include:\n\n<b>usage.md</b> - This file will be injected at the top of the `Usage` section in your README.md. The file should be pure markdown, there will be no templating or substitution done on this file.\n\n<b>description.md</b> - This file will be injected at the top of the `Description` section in your README.md. The file should be pure markdown, there will be no templating or substitution done on this file.\n\n<b>defaults.yml</b> - This file should contain descriptions for defaults defined in your project, if any. This file is YAML and should match the keys in your `defaults/main.yml` or corresponding defaults file. Values should be strings that are used as descriptions when compiling the defaults markdown table\n",
    "bugtrack_url": null,
    "license": "Copyright (c) 2018 The Python Packaging Authority  Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:  The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.  THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
    "summary": "Generate and collate documentation for Ansible projects",
    "version": "1.0.8",
    "split_keywords": [
        "ansible",
        "documentation",
        "generator",
        "generate"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "d44214a201ab553168d3b5e9a93e19b2",
                "sha256": "79c62db7cada6768c4d2ce04852203c7675c2a0df8779cf3d58ec00c78a40883"
            },
            "downloads": -1,
            "filename": "ansidocs-1.0.8.tar.gz",
            "has_sig": false,
            "md5_digest": "d44214a201ab553168d3b5e9a93e19b2",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 15277,
            "upload_time": "2022-12-21T18:41:07",
            "upload_time_iso_8601": "2022-12-21T18:41:07.106771Z",
            "url": "https://files.pythonhosted.org/packages/92/26/f8908fd25c74b28ef89f9d198e9bfd4d6cf7cf799ebbe6931f7722efa7cf/ansidocs-1.0.8.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2022-12-21 18:41:07",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "lcname": "ansidocs"
}