Consider sphinx extension to render different versions of examples code

[prjemian]

@rayosborn suggested:

Incidentally, I came across a Sphinx extension at https://sphinxcontrib-osexample.readthedocs.io/. It allows you to add code tabs, so if we agree on code examples, we can have a nexusformat tab and a h5py tab, which the users are free to click on. Perhaps @prjemian can say whether he thinks the extension could work for the NeXus manual. Having one API example follow the other would quickly make the documentation unwieldy, and mixing them up would make it incoherent. This might be the best solution, if it works, because the user could choose what to look at.

Originally posted by @rayosborn in #807 (comment)

[prjemian]

Examine this extension to see if can render different code examples. The web page says:

It’s intended to be used for displaying package manager examples. (e.g., apt install or dnf install).

then

Currently supported are: Debian, Ubuntu, Fedora, CentOS, OSX

but the example suggests the tab names are defined in .rst code.

[prjemian]

This might lead us to a refactor of the code examples. One could imagine tabs for nexusformat, h5py, h5lite, NAPI-C, h5lite, NAPI-Fortran, h5lite, ... to create the same HDF5/NeXus data file.

[benajamin]

The extension Ray linked to is derived from sphinxcontrib-examplecode, which claims to do what we want, while the former adapts the tabs idea to installation commands on different OS's (includes some checking that the commands are correct). Both of these extensions use the Sphinx.info() command, which was deprecated and removed long ago and they should be updated to use the logging API before we can use them. This is pretty easily fixed, but I haven't got the promised tabs to work properly yet.

[benajamin]

Google says I should probably just use the Sphinx-tabs extension that does exactly what we want and is still being maintained.

[benajamin]

I can get the Sphinx-tabs to work, but including text from other files (via .. include:: ) isn't working for me in the code-tabs. I have seen a claim that it works for at least one person, so I will keep trying.

[benajamin]

Progress! include directives do work within the standard tabs and group-tabs, but not in code-tabs.

[benajamin]

I think the recommended Sphinx code would be like:

.. tabs::
   .. group-tab:: Python (h5py)
      .. literalinclude:: BasicWriter_h5py.py
                :tab-width: 4
                :linenos:
                :language: python
   .. group-tab:: Python (nexusformat)
      .. literalinclude:: BasicWriter_nexusformat.py
                :tab-width: 4
                :linenos:
                :language: python
   .. group-tab:: C++
      .. literalinclude:: BasicWriter.cpp
                :tab-width: 4
                :linenos:
                :language: c++

Plus the sphinx-tabs needs to be installed on the compiling system and extensions = ['sphinx_tabs.tabs'] included in the conf.py.

[benajamin]

@prjemian @PeterC-DLS
Do I need to inform the make system of the added dependency on the sphinx-tabs package (installable via pip)?

[prjemian]

This dependency is registered in the /environment.yml file. See #899 where it is suggested to create an additional requirements.txt file when setting up a python environment that does not use conda.

[benajamin]

Printing the html page will print the already open tabs, just as they appear in the browser window at that time.
Compiling a PDF shows firstly the list of tab headings, then each tab in sequence. It would be preferable to have the tab headings printed at the top of each corresponding tab-content, but decent doc-strings at the top of each code file are a functional substitute.
I think that these behaviours are appropriate for our usage and I will continue work implementing tabs for all of the python code in section 2.1.2 of the manual.

[benajamin]

An implementation is underway in branch 854-code-tabs and I'm trying to include tabs (holding nexusformat and h5py based code) throughout section 2.1.2. of the manual and make it somewhat self-consistent in as minimal a fashion possible. This experience is already showing that the code examples being written in #807 lack the context to be useful and so any rewriting of the code examples will require considering the entire situation that the code examples are based on (i.e. the WONI instrument).

[prjemian]

Related to

• Adding nexusformat examples to the manual #1117

[prjemian]

Closed with #1117