[SciPy-dev] Of use and abuse of sphinx's math directive

[jh at physics.ucf.edu]

2008/10/28 St?fan van der Walt <stefan at sun.ac.za>:
> 2008/10/28 Gael Varoquaux <gael.varoquaux at normalesup.org>:
>> Sphinx is great, will all love Sphinx. But I do wonder if sometimes we do
>> not use the math directive a bit too much, eg the "n" and "n-1" on:
>> http://scipy.org/scipy/scipy/browser/trunk/scipy/cluster/hierarchy.py#L1090
>> (this is just an example that I picked randomly).
>>
>> When the formula written is simple-enought that its readibility is not
>> too much affected by having it in text in the Sphinxified document, I
>> think it is a pitty to render the plain text docstrings hard-to-read.
>
> Certainly -- the idea is to use the :math: tag sparingly.

This is a classic case of too many constraints.  Not only is it right
to do one thing in plain text and another in formatted print, but I
think the preferred solution will change from leave it alone (today)
to flag it (future).  The use of the plain text doc interface is
diminishing.  It will always have some uses, such as on a text-only
terminal or while editing a function in an ap like emacs (i.e.,
looking at the function's own docstring while editing the code).  But,
people are going to get used to doc interfaces more useful than
help(), and those will soon be able (optionally) to tell your browser
to pull up a given page rather than feeding you the help in the
terminal.

So my suggestion is that we keep the text clean for now, but we flag
such pages in a comment so that they're easy to find when we do want
to go through the pages and switch to tagging everything.  How about a
checkbox for "This page contains unflagged, inline math" on the doc
wiki.  That could generate a comment in the source code but not in the
docstring.  It would then be easy to identify the pages to fix if/when
we decide to do so.  Finding the locations in the page to do that
isn't hard and we're not talking the majority of pages.

--jh--