{"id":14109828,"url":"https://github.com/archf/ansidoc","last_synced_at":"2025-04-10T05:34:10.638Z","repository":{"id":57410566,"uuid":"62809908","full_name":"archf/ansidoc","owner":"archf","description":"A simple tool to generate Ansible roles' documentation","archived":false,"fork":false,"pushed_at":"2020-01-28T13:17:32.000Z","size":47,"stargazers_count":11,"open_issues_count":1,"forks_count":3,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-03-24T06:51:46.978Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/archf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-07-07T13:43:19.000Z","updated_at":"2023-08-09T02:59:26.000Z","dependencies_parsed_at":"2022-08-28T01:14:02.068Z","dependency_job_id":null,"html_url":"https://github.com/archf/ansidoc","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/archf%2Fansidoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/archf%2Fansidoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/archf%2Fansidoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/archf%2Fansidoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/archf","download_url":"https://codeload.github.com/archf/ansidoc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247726060,"owners_count":20985821,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-14T10:02:31.000Z","updated_at":"2025-04-10T05:34:10.500Z","avatar_url":"https://github.com/archf.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Ansidoc\n\nA simple tool to generate ansible role's documentation.\n\n## Usage\n\nThis tool generates a `README.md` file using data from multiple sources.\n\n* From role content:\n  * role `defaults/main.yml`\n  * role `vars/*.yml`\n* You content.\n  * role `docs/*.yml`\n  * role `docs/*.md`\n\nContent of your role `vars/*` and `defaults/*` will also be literally inserted\nin between `yaml` codeblocks. Put nice comments//explanations of variable's\npurpose in them!\n\nThe role `docs` directory may contain YAML files that will be parsed. Variables\nwithin will be use to enrich the resulting `README.md` file. All markdown files\nwill also be include. Top header must be of level H2. Currently there are no\nmechanism to defined the inclusion order.\n\n### Prepare your role\n\nFor best results, create a `docs/\u003cyou-var-file\u003e.yml` file inside your role and fill those\nvariables:\n\n```yaml\n---\n\ngithub_account: \u003cyour-role-github-account-username\u003e\ntodos: [] # (optional) list of todos to print in your README file\n```\n\n### cli\n\n```shell\nusage: ansidoc [-h] [-v] [-V] [-d] [-s TARGET] [-nf] [-e EXCLUDE] [-p] dirpath\n\npositional arguments:\n  dirpath               Either a 'roles_path' wich is a roles' directory or a\n                        path to a single role. If 'roles_path' basename is\n                        'roles' it will loop over subdirectories assuming each\n                        of them contains a role.\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -v, --verbose         increase output verbosity\n  -V, --version         show program's version number and exit\n  -d, --dry-run         dry run, Outputs pure markdown to stdout nothing is\n                        written to disk\n  -s TARGET             (docs | README.md) Create a symlink in PWD to TARGET.\n                        This is useful when used from sphinx as you cannot add\n                        relative entries such as '../*' in the toctree. If\n                        unspecified, no symlink is created.\n  -nf, --no-ansidoc-footer\n                        Do not render the ansidoc project footer.\n  -e EXCLUDE, --exclude EXCLUDE\n                        csv list of role names to exclude. Must match\n                        directory name found under specified 'dirpath'\n  -p, --private         Consider role(s) private, e.g.: Skip installation from\n                        github part from rendered template.\n```\n\n### From sphinx\n\nYou can import in your code and pass arguments similarly as you would do on the\ncli.\n\nFor example:\n\n```python\nfrom ansidoc import Ansidoc\nansidoc = Ansidoc(dirpath=\u003cpath/to/role\u003e, dry_run=True)\nansidoc.run()\n```\n\n## wishlist\n\n- role dependency grapher\n- role variables analysis (to audit what is defined where)\n- create sphinx documentation for this program\n- make this a sphinx plugin\n- include mardown files in defined order (alphabetical?, number the files?)\n- override parts of template with custom one.\n  - search paths to find templates (`.ansidoc/templates/*`?)\n- multi-role variables\n  - search paths to find config (`.ansidoc/config.yml`?)\n  - exclude list configurable in config file\n\n## License\n\nMIT.\n\n## Similar Projects\n\n* [Ansible-DocGen](https://github.com/toast38coza/Ansible-DocGen)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farchf%2Fansidoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farchf%2Fansidoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farchf%2Fansidoc/lists"}