search

visit-dav / visit

VisIt - Visualization and Data Analysis for Mesh-based Scientific Data
https://visit.llnl.gov
BSD 3-Clause "New" or "Revised" License
434 stars 112 forks source link

Better sphinx strategy for multi-platform, multi-context #4394

Open markcmiller86 opened 4 years ago

markcmiller86 commented 4 years ago

Most of our documentation is platform-independent. But, not all of it. Sometimes, we need to have specific documentation for a given Platform (Windows, Unix, OSX) or maybe even specific to variants of Unix.

Currently, where we need to do this, we just write something like On Windows... but on Unix.... This is unsatisfactory and, worse, can get unwieldly. I wonder if there is a better strategy and/or whether Sphinx has built-in support for this. This isn't to be confused with multi-language or internationalization support. I looked at Sphinx Domains and maybe that could work. There is also an .. only: <some-tag-here> directive where we can have text conditionally constructed. But, that then requires wholey separate versions of the manual be rendered for specific tags and is also unsatisfactory.

I was hoping something where we could have a section with tabs with names like Windows, Unix and OSX and the user can select a tab to see stuff specific to that platform.

markcmiller86 commented 4 years ago

I could potentially see some merit in having platform-specific screen shots. If we were able to automate the process of collecting screen shots then it could potentially make for higher quality manual and then generating wholly new Windows manual, a Unix manual and an OSX manual might not be such a bad idea.