[tor-bugs] #7223 [Ooni]: Streamline the creation of test specifications

[Tor Bug Tracker & Wiki]

#7223: Streamline the creation of test specifications
---------------------------+------------------------------------------------
 Reporter:  hellais        |          Owner:  hellais
     Type:  enhancement    |         Status:  new    
 Priority:  normal         |      Milestone:         
Component:  Ooni           |        Version:         
 Keywords:  specification  |         Parent:         
   Points:                 |   Actualpoints:         
---------------------------+------------------------------------------------
 Currently we write test specifications here:
 https://trac.torproject.org/projects/tor/wiki/doc/OONI/Tests, but we also
 include the details of a test inside of the code.

 To avoid having to manually keep in sync the test specification on the
 wiki and the one inside of the code it would be ideal if we had a way to
 automatically generate from the code the test specification.

 We should take the data from the docstrings of the test specification and
 create markup to go on either the trac wiki page or on the OONI docs
 stored on https://ooni.readthedocs.org/

 I see to possible routes for doing this:

 1) we do something custom that runs on every file the methods that we use
 in runner.py do detect if a class if of the right class and then using
 something similar to this:
 https://github.com/globaleaks/GLBackend/blob/master/docs/generate_spec.py
 we generate the test specification

 2) Use the autodoc feature of sphinx:
 http://sphinx.pocoo.org/ext/autodoc.html#module-sphinx.ext.autodoc.

 I believe the second option is optimal.

-- 
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/7223>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online