Re:A Framework for Writing Better Documentation
by ldes on Tuesday February 02, 2021 @03:19PM
(#26006067)
One way to achieve this is using Sphinx (documentation generator based on reStructuredText https://www.sphinx-doc.org/en/master/) in combination with the Contentui extension (https://sphinxcontrib-contentui.readthedocs.io/en/latest/tab...).
Re:A Framework for Writing Better Documentation
by mimixco on Wednesday February 03, 2021 @11:06AM
(#26014925)
We just launched a hosted wiki service called Miki that can be customized in this way. You can control page content by setting up custom groups and permissions and you can integrate with other APIs to do things like get user settings from another source.
We'll have an offline, desktop version soon. http://miki.mimix.io
Re:A Framework for Writing Better Documentation
by stsewd on Tuesday February 02, 2021 @04:01PM
(#26006589)
Another way to achive this is in sphinx is using https://github.com/executablebooks/sphinx-tabs
Re:A Framework for Writing Better Documentation
by formerly_proven on Tuesday February 02, 2021 @04:57PM
(#26007417)
sphinx-inline-tabs is probably better for this use case because all tabs with the same label are synchronized on the page. So if you want to offer different instructions for a number of environments, you only need to select it once per page.
Example: https://pip.pypa.io/en/stable/installing/#installing-with-ge...
Re:A Framework for Writing Better Documentation
by stsewd on Tuesday February 02, 2021 @05:15PM
(#26007657)
Sphinx tabs supports that https://github.com/executablebooks/sphinx-tabs#grouped-tabs, haven't used sphinx-inline-tabs
I'd like the typical docs in Markdown or Asciidoc in flat files like a static CMS but within a page I'd like to have customer/choice dependent blocks.
So some free form text and then a block with instructions that are different per environment or customer or whatever. So based on a selection I'll only show the parts for Debian or Red Hat or whatever or I'll pull customer information out of a CMS system to show the customer only the parts relevant for her environment.
I know this exists but I can't find an example now. This is what I'd like to avoid: https://docs.nginx.com/nginx/admin-guide/installing-nginx/in... I don't want to show a Debian user all the stuff she's not interested in.