# Easy documentation for roles/collection

**URL:** <https://forum.ansible.com/t/easy-documentation-for-roles-collection/6043>\
**Category:** Project Discussions\
**Tags:** python, role, documentation, collections\
**Created:** [May 28, 2024, 7:08pm UTC](https://forum.ansible.com/t/easy-documentation-for-roles-collection/6043 "2024-05-28T19:08:45Z")\
**Posts on this page:** 6\
**Page:** 1

<div class="post-metadata">

**Author:** ![lucian](https://avatars.discourse-cdn.com/v4/letter/l/eb9ed0/32.png) [@lucian](https://forum.ansible.com/u/lucian)\
**Post date:** [May 28, 2024, 7:08pm UTC](https://forum.ansible.com/t/easy-documentation-for-roles-collection/6043/1 "2024-05-28T19:08:45Z")

</div>

Hello everyone,

I wanted to share with you docsible. It helps generate documentation for Ansible roles and collections automatically.  
Docsible creates clear, organized README files with mermaid graph, making it easier to manage/read your projects.

[Examples](https://gitlab.com/docsible)

I’m interested in hearing what the community thinks about it. You can check it out here: [Docsible on GitHub](https://github.com/exaluc/docsible)

Looking forward to your feedback!

---

<div class="post-metadata">

**Author:** ![chris](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/chris/32/293_2.png) [@chris](https://forum.ansible.com/u/chris)\
**Post date:** [May 28, 2024, 7:36pm UTC](https://forum.ansible.com/t/easy-documentation-for-roles-collection/6043/2 "2024-05-28T19:36:37Z")

</div>

Nice one, have you considered an additional command line option to output the results to a file other than `README.md`? Personally I’d rather write the results to a different file name and link from the `README.md`.

I have run `docsible` for one role but I couldn’t commit it to share it as it failed the `pre-commit` config for Markdown files, in `.pre-commit-config.yaml` I have:

```yaml
repos:
  - repo: https://github.com/jackdewinter/pymarkdown.git
    rev: v0.9.19
    hooks:
      - id: pymarkdown
        name: Markdown Lint
        args:
          - scan
          - README.md

```

And I also have a `.pymarkdown.yml` to disable the line length check:

```yaml
plugins:
  md013:
    enabled: false

```

Would it be possible to output Markdown that can pass this linting?

---

<div class="post-metadata">

**Author:** ![lucian](https://avatars.discourse-cdn.com/v4/letter/l/eb9ed0/32.png) [@lucian](https://forum.ansible.com/u/lucian)\
**Post date:** [May 28, 2024, 7:53pm UTC](https://forum.ansible.com/t/easy-documentation-for-roles-collection/6043/3 "2024-05-28T19:53:21Z")

</div>

> [@chris](#):
>
> ```auto
> repos:
> - repo: https://github.com/jackdewinter/pymarkdown.git
> rev: v0.9.19
> hooks:
> - id: pymarkdown
> name: Markdown Lint
> args:
> - scan
> - README.md
> 
> ```

Hello @chris,  
Yes, file name with path can be different, on issues github page there is a feature request template.

You should get a message like this if the yaml in tasks folder is diff than a role tasks:  
Unexpected data type for tasks in .pre-commit-config.yaml. Skipping.

Is your repo role public ? Can I test it ?

---

<div class="post-metadata">

**Author:** ![chris](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/chris/32/293_2.png) [@chris](https://forum.ansible.com/u/chris)\
**Post date:** [May 28, 2024, 7:55pm UTC](https://forum.ansible.com/t/easy-documentation-for-roles-collection/6043/4 "2024-05-28T19:55:21Z")

</div>

> [@lucian](#):
>
> Is your repo role public ? Can I test it ?

Yes they all are, the one I tested it on is [this one](https://git.coop/webarch/php), it is also [mirrored to GitHub](https://github.com/webarch-coop/ansible-role-php).

I’ve [opened a feature request](https://github.com/exaluc/docsible/issues/16) for the output filename.

---

<div class="post-metadata">

**Author:** ![lucian](https://avatars.discourse-cdn.com/v4/letter/l/eb9ed0/32.png) [@lucian](https://forum.ansible.com/u/lucian)\
**Post date:** [May 28, 2024, 8:10pm UTC](https://forum.ansible.com/t/easy-documentation-for-roles-collection/6043/5 "2024-05-28T20:10:36Z")

</div>

Ok, I get your problem now.  
I have generate the readme and yes table result with vars values are to long.  
You can extract the base jinja2 [template](https://github.com/exaluc/docsible/blob/main/docsible/markdown_template.py) from docsible and create your own readme template.  
Just pass --md-template with path.  
I suggest you to only show link to var and not the value, the vars contains a big list.  
Thank you for your reply, I’ll try to find a solution for long lists in vars.

---

<div class="post-metadata">

**Author:** ![Leo](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/leo/32/23_2.png) [@Leo](https://forum.ansible.com/u/Leo)\
**Post date:** [June 4, 2024, 11:08pm UTC](https://forum.ansible.com/t/easy-documentation-for-roles-collection/6043/6 "2024-06-04T23:08:50Z")

</div>

Hi @lucian , thanks for sharing! I’m moving the thread to the #Project Discussions category, as it seems this can be considered as a discussion related to the whole Ansible projects documentation efforts.

The [@Docs](https://forum.ansible.com/groups/docs) Working Group might be interested!

For reference, the original category (#Social Space) is mostly for “off topic” things, like hobbies or other social exchanges, ideally, stuff that doesn’t fit elsewhere. Checking other posts, we probably need to curate it a bit… sorry about that!