investigate Sphinx doctest for usage documentation

[Anders Markvardsen]

Martyn identified Sphinx doctest, ​http://sphinx-doc.org/ext/doctest.html, as a possible candidate for creating usage documentation section for #8919

Here investigate if Sphinx doctest tick the boxes

[Anders Markvardsen]

The following rst code:

.. testsetup:: *

   from mantid.simpleapi import *

Example 1:   

.. testcode:: Ex1

   # create some workspace
   dataX = [0, 1]
   dataY = [0, 2]
   ws = CreateWorkspace(dataX, dataY)
   
   # do blah blah   
   
   # print output for testing
   print ws.readY(0)[1]   

.. testcleanup:: Ex1

   DeleteWorkspace(ws)
   
.. testoutput:: Ex1
   :hide:
   
   2.0



Example 2:
   
.. testcode:: Ex2

   # create some workspace
   dataX = [0, 1]
   dataY = [0, 2]
   ws = CreateWorkspace(dataX, dataY)
   
   # do blah blah   
   
   # print output for testing
   print ws.readY(0)[1]   

.. testcleanup:: Ex2

   DeleteWorkspace(ws)
   
.. testoutput:: Ex2
   :hide:
   
   3.0

Upon running 'make doctest' the above will generate the output:

CreateWorkspace-[Notice] CreateWorkspace started
CreateWorkspace-[Notice] CreateWorkspace successful, Duration 0.00 seconds
**********************************************************************
File "Algorithms\doc\Rebin.rst", line 69, in Ex2
Failed example:
    # create some workspace
    dataX = [0, 1]
    dataY = [0, 2]
    ws = CreateWorkspace(dataX, dataY)

    # do blah blah

    # print output for testing
    print ws.readY(0)[1]
    #print 2+2  # this will give output
Expected:
    3.0
Got:
    2.0
DeleteWorkspace-[Notice] DeleteWorkspace started
DeleteWorkspace-[Notice] DeleteWorkspace successful, Duration 0.00 seconds
CreateWorkspace-[Notice] CreateWorkspace started
CreateWorkspace-[Notice] CreateWorkspace successful, Duration 0.00 seconds
DeleteWorkspace-[Notice] DeleteWorkspace started
DeleteWorkspace-[Notice] DeleteWorkspace successful, Duration 0.00 seconds
1 items passed all tests:
   1 tests in Ex1
**********************************************************************
1 items had failures:
   1 of   1 in Ex2
2 tests in 2 items.
1 passed and 1 failed.
***Test Failed*** 1 failures.
2 items passed all tests:
   1 tests in Ex1 (cleanup code)
   1 tests in Ex2 (cleanup code)
2 tests in 2 items.
2 passed and 0 failed.
Test passed.

Doctest summary
===============
    2 tests
    1 failure in tests
    0 failures in setup code
    0 failures in cleanup code
build finished with problems.

and the output from running 'make html' is shown in the attached makeHTMLout.PNG

[Anders Markvardsen]

output from running 'make html'

[Anders Markvardsen]

From the observation in Comment 2 sphinx doctest appear to tick the boxes:

• Can support multiple example
• Can display example as HTML
• Examples can be unit tested to a degree sufficient for this (not suppose to be full blown unit tests, this is done separately)
• provide option for setup and cleanup and hide output in html if this is found useful

[Anders Markvardsen]

To tester:

Agree observations in Comments 2 and 3

[Peter Parker]

Yep. Sphinx is pretty cool.

[Stuart Campbell]

This ticket has been transferred to github issue ​10315