Process docstrings with Sphinx

Processes docstrings with Sphinx. Can also be used as a commandline script:

python sphinxify.py <text>

AUTHORS:

  • Tim Joseph Dumol (2009-09-29): initial version
sagenb.misc.sphinxify.generate_configuration(directory)

Generates a Sphinx configuration in directory.

INPUT:

  • directory - string, base directory to use

EXAMPLES:

sage: from sagenb.misc.sphinxify import generate_configuration
sage: import tempfile, os
sage: tmpdir = tempfile.mkdtemp()
sage: generate_configuration(tmpdir)
sage: open(os.path.join(tmpdir, 'conf.py')).read()
'\n...extensions =...'
sagenb.misc.sphinxify.is_sphinx_markup(docstring)

Returns whether a string that contains Sphinx-style ReST markup.

INPUT:

  • docstring - string to test for markup

OUTPUT:

  • boolean
sagenb.misc.sphinxify.sphinxify(docstring, format='html')

Runs Sphinx on a docstring, and outputs the processed documentation.

INPUT:

  • docstring – string – a ReST-formatted docstring
  • format – string (optional, default ‘html’) – either ‘html’ or ‘text’

OUTPUT:

  • string – Sphinx-processed documentation, in either HTML or plain text format, depending on the value of format

EXAMPLES:

sage: from sagenb.misc.sphinxify import sphinxify
sage: sphinxify('A test')
'...<div class="docstring">\n    \n  <p>A test</p>\n\n\n</div>'
sage: sphinxify('**Testing**\n`monospace`')
'...<div class="docstring"...<strong>Testing</strong>\n<span class="math"...</p>\n\n\n</div>'
sage: sphinxify('`x=y`')
'...<div class="docstring">\n    \n  <p><span class="math">x=y</span></p>\n\n\n</div>'
sage: sphinxify('`x=y`', format='text')
'x=y\n'
sage: sphinxify(':math:`x=y`', format='text')
'x=y\n'