Easy documentation for roles/collection

Project Discussions
, , ,
1

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

I’m interested in hearing what the community thinks about it. You can check it out here: Docsible on GitHub

Looking forward to your feedback!

2 Likes
2

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:

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:

plugins:
  md013:
    enabled: false

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

3

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 ?

4

Yes they all are, the one I tested it on is this one, it is also mirrored to GitHub.

I’ve opened a feature request for the output filename.

5

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 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.

1 Like
6

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 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!

2 Likes