Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
# -*- coding: utf-8 -* 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 """
#***************************************************************************** # Copyright (C) 2009 Tim Dumol <tim@timdumol.com> # # Distributed under the terms of the BSD License #*****************************************************************************
r""" 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 sage.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'
TESTS::
sage: n = len(sys.path) sage: _ = sphinxify('A test') sage: assert n == len(sys.path) """
else:
# Sphinx constructor: Sphinx(srcdir, confdir, outdir, doctreedir, # buildername, confoverrides, status, warning, freshenv).
[parsers] smart_quotes = no """)
confoverrides, None, None, True)
# We need to remove "_" from __builtin__ that the gettext module installs
# Translate URLs for media from something like # "../../media/...path.../blah.png" # or # "/media/...path.../blah.png" # to # "/doc/static/reference/media/...path.../blah.png" 'src="/doc/static/reference/media/\\2"', output) # Remove spurious \(, \), \[, \]. else: print("BUG -- Sphinx error") if format == 'html': output = '<pre class="introspection">%s</pre>' % docstring else: output = docstring
import sys if len(sys.argv) == 2: print(sphinxify(sys.argv[1])) else: print("""Usage: %s 'docstring'
docstring -- docstring to be processed """) |