Transferring existing template?

[InTheCloudDan]

This tool is looking really great! I was wondering if you help me understand how to transfer a template to this design? I generated a site directly and it looks nice but I am looking to get closer to the native ansible docs. I found this template: https://github.com/alibaba/ansible-provider-docs/blob/master/docs/templates/plugin.rst.j2

And so far I've hacked in changing the delimiter and a bunch of the functions they use, but based on reading through it seems like it could be made cleaner because of newer versions of jinja. I was just wondering if you give your insight on if you think it's possible to migrate it over.

[tadeboro]

Full disclosure: I suck hard at designing things that are not APIs, so do not expect any useful advice from the UX department ;)

I am afraid that we cannot directly transfer Ansible's existing template. The main (maybe only?) reason for this is the html_ify filter that we did not care to add. And Ansible's built-in template has a lot of raw HTML. (On a side note: we should document what filters are available to template authors.)

There are a few things we could do to rectify this situation. We could port the required filters. Or we could try to render reStructuredText tables directly. Not really sure what would be the best way forward. Any ideas or suggestions?

[InTheCloudDan]

it looks like html_ify is pretty close to the general rst_ify right? This is the local hacking I did to make that template work: https://gist.github.com/InTheCloudDan/072ca73786910282e76baffe2d2b0e30 so maybe porting the filters is easier? Just for my use case, I'd love to get rid of the to_kludge_ns and from_kludge_ns

[tadeboro]

I quickly went through the upstream template and checked what we would need to add to fully support it. The list I came up with is:

• documeted_type filter
• html_ify filter
• list test

If we copy implementations from ansible, we can start thinking about rendering the documents that look lie upstream documentation. There is still a question of theme, but that is out of scope of this project, since reStructuredText is our end target,

We can get rid of the *_kludge_ns filters and replace them with jinja2 namespaces without any problem. I will set the minimum jinja2 version in the setup.cfg to 2.10 and that will be the end of it.