Comment by lars_francke | Hacker News Reader

Comment by lars_francke | Hacker News Reader

Parent Full thread

I have a semi-related question: I'm looking for a customizable documentation system.

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.

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

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

Another way to achive this is in sphinx is using https://github.com/executablebooks/sphinx-tabs

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

Sphinx tabs supports that https://github.com/executablebooks/sphinx-tabs#grouped-tabs, haven't used sphinx-inline-tabs

Pytorch has a really good one for installation, but it seems to be handcrafted JavaScript. I would love if .rst on readthedocs offered some declarative way to do it.

As mentioned above, sphinx-tabs will get the job done.

Reply on news.ycombinator.com