Writing documentation¶
This section describes certain not obvious details in writing documentation for Pymote in sphinx.
Intersphinx¶
To auto-reference external document in with intersphinx:
set intersphinx_mapping in
conf.py
:intersphinx_mapping = { 'python': ('http://docs.python.org/', None), 'numpy': ('http://docs.scipy.org/doc/numpy/', None), 'scipy': ('http://docs.scipy.org/doc/scipy/reference/', None), }
reference in docs with
`:py:<type>:`<ref>`
i.e.:py:class:`numpy.poly1d`
. For finding reference manually read on.
Finding reference¶
If <type>
is not explicitly known it can be found out from objects.inv
files found in URLs in intersphinx_mapping above.
To get and decode objects.inv for numpy:
$ wget http://docs.scipy.org/doc/numpy/
$ ipython
In python:
import zlib
with open("objects.inv","r") as f:
inv_lines = f.readlines()
lista = zlib.decompress(''.join(inv_lines[4:])).split('\n')
with open('objects_numpy.inv','w') as f:
for line in lista:
f.write(line+'\n')
To find reference for numpy.poly1d
serach for it in decoded file objects_numpy.inv
.
The line should include word class
In documentation include :py:class:`numpy.poly1d`
For scipy.stats.norm
:
find scipy.stats.norm -> data -> :py:data:`scipy.stats.norm`
Readthedocs.org¶
In order for readthedocs.org to make documentation it needs to have certain packages accessible.
On readthedocs.org admin page check option
Use virtualenv
AndUse system packages
and inRequirements file
put the name to the requirements file in repo (i.e.requirements.txt
).Make
readthedocs.py
module and put it indocs
folder with Mock class found hereIn documentation
conf.py
put the following lines to import mock class for certain modules that are not present in virtual environment.if os.environ.get('READTHEDOCS', None) == 'True': sys.path.insert(0,'.') from readthedocs import * sys.path.pop(0)