[SciPy-Dev] How to preview changes to a doc file?

[Paul van Mulbregt]

Thanks Evgeni,
See below for how that failed and what made it work.

> On Jun 7, 2017, at 6:51 PM, Evgeni Burovski <evgeny.burovskiy at gmail.com> wrote:
> 
> On Wed, Jun 7, 2017 at 11:12 PM, Paul van Mulbregt
> <p.vanmulbregt at comcast.net> wrote:
>> What is the recommended way to preview any documentation changes, such as
>> after modifying restructured text (rst) files?
> 
> $ cd doc
> $ make html-scipyorg
> 
> which builds the docs *for the installed scipy*. To build the docs for
> the dev tree, use
> 
> $ python runtests.py --shell
> $ cd <path-to-scipy-tree>/doc
> $ make html-scipyorg

This last step failed due to "You need a recent enough version of matplotlib".
But the doc build is using a Python2.7, even though the python on my path is 3.6.
I tracked down the Py2.7 that is being used, then installed numpy, scipy, matplotlib in *that* Py27 installation and repeated it and this time the make succeeded.
The process does seem to be explicitly asking for a python2.7 to build the doc.  The first command in scipy/doc/Makefile is "PYVER = 2.7"

[~/src/python/scipy/doc]
$ make html-scipyorg
mkdir -p build/html build/doctrees
LANG=C python2.7 /usr/local/bin/sphinx-build -t scipyorg -b html -d build/doctrees   source build/html-scipyorg 
Running Sphinx v1.6.2
Scipy (VERSION 1.0.0.dev0+69ce114)
...

Is there some other env variable that needs setting in order to build with Py3.x?


> 
> 
> 
>> After adding some additional math to an rst file, I’d like to see the result
>> of the change, but haven’t found a good way to do so.
>> [I’m using a Mac, with Python 3.6.]
>> 
>> * Attempts to build the scipy doc have not succeeded for me ("setup.py
>> build_sphinx" generates lots of dvipng errors; perhaps building the doc
>> requires Py2.7???)
> 
> Not anymore (modulo https://github.com/scipy/scipy/issues/7369 which
> might be a user error).
> 
> 
>> * The Mac editor Atom has some rst preview packages, but I haven’t found one
>> that can handle the \begin{eqnarray*} constructs in the scipy rst files.
>> * Stand-alone rst-viewers which then opened in a browser didn’t like the
>> math either.
>> * One online viewer http://rst.ninjs.org did render the math in a fashion,
>> after I had removed the ":nowrap:", and converted the backtick  :math:`XXX`
>> to stand-alone math.  But it was a poor rendering when compared to the
>> actual scipy html.
>> 
>> How do you preview doc changes?
>> 
>> Thanks,
>> Paul
>> 
>> 
>> 
>> _______________________________________________
>> SciPy-Dev mailing list
>> SciPy-Dev at python.org
>> https://mail.python.org/mailman/listinfo/scipy-dev
>> 
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at python.org
> https://mail.python.org/mailman/listinfo/scipy-dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20170607/856b2307/attachment-0001.html>