[NeXus-tech] NXdetector manual

[Pete Jemian]

Eugen:


starting with this page, there are answers to your questions:
http://download.nexusformat.org/doc/html/examples/h5py/index.html

On 11/25/2013 10:47 AM, Wintersberger, Eugen wrote:
> There are several problems that I have with rst (but may you can help
> me)
> .) how to place images properly and reference them in the text

browse to that page and click on the link for "Show Source"

This is one way to place a figure with a reference tag in Sphinx RST:

	.. _Example-H5py-Plot:
	
	.. figure:: s00008.png
	    :alt: Example-H5py-Plot
	    :width: 80%
	
	    plot of our *mr_scan*

Later, this figure is referenced with this Sphinx RST code:

    Compare this with
    :ref:`Example-H5py-Plot`

See the resulting reference to the figure in the HTML page, search the 
HTML page for this:  "Compare this with"

> .) how difficult is it to use mathematical expressions (is mathjax used
> for HTML output?)

In Sphinx, choice of the math rendering engine is made global for all 
pages of a document in the `conf.py` file.  The math uses LaTeX 
formatting.  MathJax is rendered in the browser.  For the NeXus manual 
these Sphinx extensions were chosen to display math instead of mathjax 
since the math they showed displayed more consistently on more systems 
than using mathjax::

   extensions.append( 'sphinx.ext.pngmath' )
   extensions.append( 'matplotlib.sphinxext.mathmpl' )

Here is an example page showing math in a section title:
http://www.cansas.org/formats/canSAS2012/1.0/doc/basics.html#q-vector-magnitude

Here is a NeXus manual page showing inline math (greek symbols, that is):
http://download.nexusformat.org/doc/html/applying-nexus.html#step-1-think-hard-about-data

The NeXus manual has no standalone math equations to show as examples. 
Here is a contrived example:

   .. _oneline.math.example:

   .. math:: (a + b)^2 = a^2 + 2ab + b^2

   .. _multiline-math-example:

   .. math::

      (a + b)^2 = a^2 + 2ab + b^2

      (a - b)^2 = a^2 - 2ab + b^2

   In RST, you can use :ref:`oneline inline.math.example` or
   :ref:`multiline multiline-math-example` math equations
   or you can write math inline: :math:`E \lambda = h \nu`.
   See the Sphinx documentation [#]_ or matplotlib [#]_ for more help.

   .. [#] http://sphinx-doc.org/ext/math.html
   .. [#] http://matplotlib.org/sampledoc/extensions.html

Elsewhere on the h5py example page is math used inline

> .) how to get code snippets into the text that can be referenced
> throughout the text and have nice syntax highlighting (I currently use
> the minted package in Latex which uses pygmented for generating the
> highlighted code).

Syntax highlighting is handled by the Python pygments package (same 
basis as pygmented?) with the 'sphinx' style.  When you declare a code 
snippet in the RST code, you can (optionally) declare what language is 
used and pygments will apply syntax highlights.  These are colorful 
within the theme of the chosen document.  The NeXus manual has a theme, 
"sphinxdoc", which is not as high-contrast as others, such as the 
"default" theme (e.g., http://docs.python.org/2/library/string.html). 
It was thought (a design choice) that when everything was as 
high-contrast as the default theme, there was no real way to make 
something standout when necessary.

On http://download.nexusformat.org/doc/html/examples/h5py/index.html:

.. compound::

     .. rubric:: *BasicWriter.py*: Write a NeXus HDF5 file using Python 
with h5py

     .. _Example-H5py-BasicWriter:

     .. literalinclude:: BasicWriter.py
	    :tab-width: 4
	    :linenos:
	    :language: guess

Then, elsewhere, this could be referred to with this RST code:

   In the main code section of
   :ref:`BasicWriter.py <Example-H5py-BasicWriter>`

Note:  It is a well-known limitation that Sphinx does not provide 
out-of-the-box numbering for equations, figures, and tables.  See the 
discussion lists if this is something you really need.  There are some 
ad hoc implementations.  It's a drawback for sure but not a reason to 
not use RST.

Pete