matplotlib / sampledoc Goto Github PK

https://matplotlib.org/sampledoc/index.html is outdated and contains some errrors that already have been fixed in the main branch 5 years ago (70f7888).

similar to nilmtk/nilmtk#87

see the fix in nipy/nitime#111

Copy of : matplotlib/matplotlib#5220

I noticed just now that sampledoc:

http://matplotlib.org/sampledoc/index.html

uses Lena for the top banner lettering background. It would be good to change that for the usual reasons (questionable taste, copyright). Is that acceptable?

First of all: thanks for making this great tutorial!

It doesn't work with matplotlib HEAD though, because matplotlib/sphinxext/ipython_directive.py no longer exists.
This worked for me:
cp ipython/docs/sphinxext/ipython_directive.py sampledoc/sphinxext

After that a missing import numpy as np in combination with @doctest on line 120 in sampledoc/ipython_directive.rst makes sphinx abort.
For me simply adding the missing import numpy as np doesn't work, the doctest still fails.
Is it possible to make the following error message point to the .rst file name and line number that contains np.random.rand(10,2) (instead of suggesting a bug in sphinx)?

$ make html
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v1.0.7
/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/matplotlib/__init__.py:908: UserWarning:  This call to matplotlib.use() has no effect
because the the backend has already been chosen;
matplotlib.use() must be called *before* pylab, matplotlib.pyplot,
or matplotlib.backends is imported for the first time.

  if warn: warnings.warn(_use_error_msg)
loading pickled environment... not yet created
building [html]: targets for 7 source files that are out of date
updating environment: 7 added, 0 changed, 0 removed
reading sources... [100%] ipython_directive                                                                                       
Exception occurred:
  File "/Users/deil/github/sampledoc/sphinxext/ipython_directive.py", line 376, in process_output
    raise RuntimeError(e)
RuntimeError: output prompt="Out[13]:" does not match out line=---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
/Users/deil/github/sampledoc/<ipython-input-13-f032a6173cb5> in <module>()
----> 1 np.random.rand(10,2)

NameError: name 'np' is not defined
The full traceback has been saved in /var/folders/9v/3cf9p8mx0n1gzcsq3mw9799m0000gn/T/sphinx-err-rTVMpU.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
Either send bugs to the mailing list at <http://groups.google.com/group/sphinx-dev/>,
or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!
make: *** [html] Error 1

There's a few more small issues:

• Line 101 in sampledoc/ipython_directive.rst needs to be indented
  Users/deil/github/sampledoc/custom_look.rst:6: (WARNING/2) Duplicate explicit target name: "sphinx".
  /Users/deil/github/sampledoc/cheatsheet.rst:7: WARNING: undefined label: cheatsheet -literal (if the link has no caption the label must precede a section header)
  /Users/deil/github/sampledoc/extensions.rst:53: WARNING: undefined label: extensions-literal (if the link has no caption the label must precede a section header)

An .rst reference seems to be broken in extensions.rst. I'm not sure what is the intended behavior.

:ref:`extensions-literal`

Alignment of the output doesn't match. I can fix locally

Hi, I am having trouble with the "customizing the look and feel" step

Issue is documented on stackoverflow here http://stackoverflow.com/questions/34856081/sphinx-tutorial-problems

I get to the repo to learn how to use Sphinx, but I find it really not that easy for Windows users.
1st, I shall look for the Sphinx scripts & exes(like sphinx-quickstart.exe);
2nd, I shall set the %SPHINXBUILD% env-var(no tip in the material).
And there's no tips for the new comers telling how to setup the Sphinx on Windows, though it's easy to type: 'python.exe setup.py install' under the source folder.

This causes a warning when I build sampledoc.

 MatplotlibDeprecationWarning: 
The Sphinx extension ipython_console_highlighting has moved from
matplotlib to IPython, and its use in matplotlib is deprecated.
Change your import from 'matplotlib.sphinxext.ipython_directive' to
'IPython.sphinxext.ipython_directive.

The change should be made in conf.py in sampledoc.

https://matplotlib.org/sampledoc/extensions.html tries to copy the files from a sphinxext dir in this repo which doesn't seem to exist.

numpydoc is now its own project which can be installed with pip or other OS/distribution package managers. Would make sense to remove sphinxext/numpydoc.py from sampledoc?

I'm not sure how active this project is, but it's missing references to mathjax.

Current SVN versions of Sphinx now include built-in support for math. There are two flavors:
pngmath: uses dvipng to render the equation
jsmath: renders the math in the browser using Javascript

https://github.com/matplotlib/sampledoc/blob/master/getting_started.rst talks about the out of date svn repository.

Given there was user interest in this project, we should probably fix this.

I'd be happy enough to do that (though a little hard pressed for time atm, but hopefully that should clear up in a couple of weeks).

There are important differences between sphinxdoc.css and basic.css from sphinx installation directory and https://matplotlib.org/sampledoc/
With the css from the installation directory the hrefs in the sitebar are not working.
So I replaced the css from the installation directory with the css that I copied from https://matplotlib.org/sampledoc/_static dir website.
You have to place them in the ....\site-packages\sphinx... installation directory because with every rebuild of your documentation the css is copied from there to your build directory!