3

I have a package that is primarily Python, and mostly meant to be used with Python. But also there are a few extra functions that are available when the module is used under Sage. The problem is that Sage doctests must be prefixed by sage: rather than >>>, and Sphinx doesn't pick these up when generating the documentation.

Is there a way to get Sphinx to recognize the sage: prefix as being equivalent to >>> when generating the HTML (or other) docs?

barryhunter
  • 20,886
  • 3
  • 30
  • 43
Dan Stahlke
  • 1,417
  • 1
  • 15
  • 20
  • Can you say how you're invoking Sphinx? I might want to experiment with it. – John Palmieri Apr 29 '14 at 14:59
  • I just ran `sphinx-quickstart`, which sets up a `conf.py` and a `Makefile` so you can do `make clean && make html`. It'll ask some questions and it's best to tell it to use a `doc` directory or it'll pollute your project dir. If you'd like to experiment with my project directly, it is `qitensor` on GitHub, and I've modified `conf.py` with the hack that I mentioned in my answer below. – Dan Stahlke Apr 29 '14 at 16:59

3 Answers3

2

Well, you can use Sage's built-in version of Sphinx and its documentation builder. Work in progress for Sage at http://trac.sagemath.org/ticket/13679 allows for building the documentation for a single Python file which is not in Sage's source tree, so you could try that.

John Palmieri
  • 1,531
  • 8
  • 13
  • Sage's ``sphinx-build`` doesn't work in this case because my Cython files are compiled against the system's libraries rather than Sage's. Also, I'd really like to allow documentation building even if the user doesn't have Sage. – Dan Stahlke Apr 25 '14 at 14:19
  • Try looking at Sage's conf.py (in `sage/doc/common`) to see if that helps. There is also a line in Sphinx's `quickstart.py`: `PROMPT_PREFIX = '> '`. You could try modifying that and see what happens. – John Palmieri Apr 28 '14 at 15:27
  • I think the magic is buried deep, deep within sage. There are some things in `sage/doctest/parsing.py` but it's not clear how it connects. Interestingly, grepping Sphinx for `['"]>>>` only turns up `highlighting.py` and modifying this doesn't fix the problem. Perhaps something in `doctest` or `pygments` is relevant. – Dan Stahlke Apr 28 '14 at 20:59
1

I finally found out how to preprocess the docstring, to change sage: to >>>. The following goes into my project's doc/conf.py:

# Adapted from http://stackoverflow.com/a/11746519/1048959
def process_docstring(app, what, name, obj, options, lines):
    for i in range(len(lines)):
        lines[i] = re.sub(r'^(\s*)sage: ', r'\1>>> ', lines[i])

def setup(app):
    app.connect('autodoc-process-docstring', process_docstring)

At least now Sphinx can parse my docstrings without generating errors. I'm still leaving this question open though because there is still a problem: the generated documentation shows >>> rather than sage:, which can be misleading to the reader.

Dan Stahlke
  • 1,417
  • 1
  • 15
  • 20
1

Okay, here's another idea: try prefacing your indented blocks with double colons. For example, in slices.rst, change

You can use numpy style indexes:

    >>> x[0, 0]
    0j

to

You can use numpy style indexes::

    sage: x[0, 0]
    0j

(I added the double colon, and I changed the prompt to sage:.) I tried this with your code, but commenting out your modification to conf.py. See the Sphinx docs for source code blocks.

Then you need to modify one Sphinx file:

diff -ur sphinx/highlighting.py sphinx/highlighting.py
--- sphinx/highlighting.py  2010-08-11 17:17:48.000000000 +0200
+++ sphinx/highlighting.py  2010-11-28 12:04:44.068642703 +0100
@@ -161,7 +161,7 @@

         # find out which lexer to use
         if lang in ('py', 'python'):
-            if source.startswith('>>>'):
+            if source.startswith('>>>') or source.startswith('sage: '):
                 # interactive session
                 lexer = lexers['pycon']
             else:
John Palmieri
  • 1,531
  • 8
  • 13
  • Thanks. It seems though that this would have a side effect of these doctests not being run, correct? Ideally, I'd like the `sage:` doctests to run when installing in sage. Also, I was trying to avoid having to monkey patch Sphinx. But maybe if a good solution is found, a patch can be submitted to them. – Dan Stahlke Apr 30 '14 at 14:10
  • Sage should run those doctests if you do `sage -t FILE`. That's how all of Sage's doctests are formatted. – John Palmieri Apr 30 '14 at 14:55
  • Okay, so the double colon doesn't make the doctests invisible then? I'll test this out as soon as I can get it to run in sage (it's giving me a `numpy.ufunc has the wrong size, try recompiling` at the moment and I can't figure out why; sage is the one compiling the cython). – Dan Stahlke Apr 30 '14 at 18:18