ENH doc is now built with the new sphinx build #6663

NelleV · 2016-06-28T18:25:40Z

Instead of relying on make.py which is the antiquated way of building sphinx
documentation, the build now relies on sphinx-build through a makefile (or
make.bat for windows).

Update the documentation.
Update travis's build system to reflect this change.

closes #5798

NelleV · 2016-06-28T18:28:48Z

Unlike before, the -W option is not set. This option makes the build fail with sphinx 1.4.1 with the following error:

Warning, treated as error:
WARNING: while setting up extension ['?', 'matplotlib.sphinxext.mathmpl']: node class 'latex_math' is already registered, its visitors will be overridden

jenshnielsen · 2016-06-28T18:45:21Z

👍 but this will need an update to travis.yml to not call make.py and an option to build the documents with warnings as errors on Travis so we can ensure that warnings don't creep back into the documentation.

QuLogic · 2016-06-29T19:51:06Z

doc/Makefile

+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+
+prepare: mpl_examples mpl_toolkits/axes_grid1/examples \


Could we not just add these symlinks in git?

symlinks + git + windows do not always play nice

Actually, this is what I did. It is much more robust than relying on python code or makefiles to them.
I don't remember ever having a problem with symlinks and windows: is that a recent issue?

Another problem if we do not rely on symlinks is that we'll have to change the make.bat, which is the window's makefile. I am not familiar with those.

tacaswell · 2016-06-29T22:50:10Z

And admittedly old link to the symlink issue is https://stackoverflow.com/questions/5917249/git-symlinks-in-windows

@JanSchulz @jbmohler Can either of you confirm that the docs can still be built in windows?

NelleV · 2016-06-29T22:52:33Z

Should I remove the symlinks and reintegrate automatically symlinking/copying those in the makefile?

tacaswell · 2016-06-29T22:59:25Z

I agree symlinks are better, lets wait to hear back from a windows user before reverting anything.

jankatins · 2016-06-30T21:04:10Z

First problem (because I have sphinx in my root env and matplotlib in a special build env -> shinx doesn't see the env matplotlib... :-/):

c:\data\external\pydata\matplotlib\doc (pr/6663)
[matplotlib_build] λ make.bat html
Running Sphinx v1.3.1

Configuration error:
The configuration file (or one of the modules it imports) called sys.exit()

-> Could you change the sys.exit(msg) to an import error or a print+sys.exit(1)?

After installing sphinx and all the stuff in my env:

c:\data\external\pydata\matplotlib\doc (pr/6663)
[matplotlib_build] λ make.bat html
Running Sphinx v1.3.1
here
Initializing GitHub plugin
loading pickled environment... not yet created
[autosummary] generating autosummary for: api\afm_api.rst, api\animation_api.rst, api\api_changes.rst, api\artist_api.rst, api\axes_api.rst, api\axis_api.rst, api\backend_bases_api.rst, api\backend_gtkagg_api.rst, api\backend_managers_api.rst, api\backend_pdf_api.rst, ..., users\recipes.rst, users\screenshots.rst, users\shell.rst, users\style_sheets.rst, users\text_intro.rst, users\text_props.rst, users\tight_layout_guide.rst, users\transforms_tutorial.rst, users\usetex.rst, users\whats_new.rst

building [mo]: targets for 0 po files that are out of date
building [html]: targets for 161 source files that are out of date
updating environment: 162 added, 0 changed, 0 removed
reading sources... [  3%] api/axes_api
Exception occurred:
  File "C:\portabel\miniconda\envs\matplotlib_build\lib\site-packages\matplotlib-2.0.0b1+1728.g068cd16.dirty-py3.5-win-amd64.egg\matplotlib\sphinxext\plot_directive.py", line 699, in run
    with io.open(source_file_name, 'r', encoding='utf-8') as fd:
FileNotFoundError: [Errno 2] No such file or directory: 'c:\\data\\external\\pydata\\matplotlib\\doc\\mpl_examples/pylab_examples/xcorr_demo.py'
The full traceback has been saved in C:\Users\jschulz\AppData\Local\Temp\sphinx-err-kbnsomyu.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.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

Is that the expected error or should I dig deeper?

jankatins · 2016-06-30T21:06:48Z

doc/users/installing.rst

+
+Since there is no canonical Windows package manager, the methods for building
+freetype, zlib, and libpng from source code are documented as a build script
+at `matplotlib-winbuild <https://github.com/jbmohler/matplotlib-winbuild>`_.


There is also a build_alllocal.cmd which has some comments on adding a conda env and then builds it in such an env.

NelleV · 2016-07-04T22:42:18Z

Hi @JanSchulz
Can you check in doc that the folder mpl_examples exists?
Thanks,
N

jankatins · 2016-07-05T13:07:27Z

c:\data\external\pydata\matplotlib\doc (pr/6663)
[matplotlib_build] λ make.bat html
Running Sphinx v1.3.1
Initializing GitHub plugin
loading pickled environment... not yet created
[autosummary] generating autosummary for: api\afm_api.rst, api\animation_api.rst, api\api_changes.rst, api\artist_api.rst, api\axes_api.rst, api\axis_api.rst, api\backend_bases_api.rst, api\backend_gtkagg_api.rst, api\backend_managers_api.rst, api\backend_pdf_api.rst, ..., users\recipes.rst, users\screenshots.rst, users\shell.rst, users\style_sheets.rst, users\text_intro.rst, users\text_props.rst, users\tight_layout_guide.rst, users\transforms_tutorial.rst, users\usetex.rst, users\whats_new.rst

building [mo]: targets for 0 po files that are out of date
building [html]: targets for 162 source files that are out of date
updating environment: 162 added, 0 changed, 0 removed
reading sources... [  3%] api/axes_api
Exception occurred:
  File "C:\portabel\miniconda\envs\matplotlib_build\lib\site-packages\matplotlib-2.0.0b1+1728.g068cd16.dirty-py3.5-win-amd64.egg\matplotlib\sphinxext\plot_directive.py", line 699, in run
    with io.open(source_file_name, 'r', encoding='utf-8') as fd:
FileNotFoundError: [Errno 2] No such file or directory: 'c:\\data\\external\\pydata\\matplotlib\\doc\\mpl_examples/pylab_examples/xcorr_demo.py'
The full traceback has been saved in C:\Users\jschulz\AppData\Local\Temp\sphinx-err-d2ep60n3.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.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

c:\data\external\pydata\matplotlib\doc (pr/6663)
[matplotlib_build] λ ls
Makefile     api/          devel/     make.bat       pyplots/           thirdpartypackages/
README.txt   build/        examples/  matplotlibrc   resources/         users/
_static/     conf.py       faq/       mpl_examples   sphinxext/         utils/
_templates/  contents.rst  glossary/  mpl_toolkits/  style_changes.rst

c:\data\external\pydata\matplotlib\doc (pr/6663)
[matplotlib_build] λ ls -la mpl_examples
-rw-r--r-- 1 jschulz 197121 12 Oct 25  2013 mpl_examples

c:\data\external\pydata\matplotlib\doc (pr/6663)
[matplotlib_build] λ cat mpl_examples
../examples/

-> It exists, but it is a textfile?

[Update]

This seems to be a git problem on windows: http://stackoverflow.com/questions/5917249/git-symlinks-in-windows

Symlink support for windows seems to be disabled per default: http://stackoverflow.com/a/11664406/1380673
[/]

jankatins · 2016-07-05T13:30:03Z

Having read a bit about it, I think for windows users, the best would be to not check in the doc\mpl_examples symlink but add it to gitignore and generate a symlink/copy the files when running the makefile/make.bat file...

NelleV · 2016-09-07T10:45:04Z

@JanSchulz sounds good. I'll do that.

Instead of relying on make.py which is the antiquated way of building sphinx documentation, the build now relies on sphinx-build through a makefile (or make.bat for windows). closes #5798

- typing make html-small-images now generates low resolution images in the documentation. - makefile now creates symlinks and others

The encoding of files (both when reading and writing) was not specified. This caused the documentation build to fail on systems not configured to use utf8 by default. Now, the sphinx-extension gen_gallery specifies the encoding when reading and writing to files and the documention builds properly on all systems.

tacaswell · 2016-09-08T19:36:24Z

doc/users/installing.rst

@@ -0,0 +1,333 @@
+.. The source of this document is INSTALL. During the doc build process,


probably should not commit this file.

NelleV · 2016-09-14T04:30:31Z

I am having trouble with the symlink on windows (more exactly, I am having problems with the make.bat file).

The reason we need to copy/symlink examples to the matplotlib folder is to be able to link to the documentation example. We could decide to switch to sphinx-gallery to build the gallery, which would allow this feature out of the box. It would also allow to have text displayed in addition to the code when displaying a gallery example, and have a title displayed in the gallery instead of the filename, and generate an ipython notebook in addition to the python file. If I am not mistaken, this is the sort of things sphinx-gallery can do: http://scikit-image.org/docs/dev/auto_examples/color_exposure/plot_ihc_color_separation.html#sphx-glr-auto-examples-color-exposure-plot-ihc-color-separation-py
sphinx-gallery can be added to the sphinxext folder and replace the gen_gallery.py present there. (the code from sphinx-gallery is actually based on matplotlib's gen_gallery.py).

Else I'll resign myself to booting under windows to test this, though I am unsure whether I'll even be able to install matplotlib there (or code).

QuLogic · 2016-09-14T21:45:32Z

Is there a way to do it without a symlink? I think we tried that on another PR and it just wouldn't work for Windows.

Long term, switching to sphinx-gallery is probably a good idea; if you wanted to start that, it might be best to do that before this PR.

NelleV · 2016-09-14T22:45:10Z

On windows, without sphinx-gallery, the folder that is symlinked on linux should be copied at every build.

NelleV · 2016-10-17T22:22:38Z

I am going to close for now, as this is going to take a while to get all the examples sphinx-gallery compatible.

mdboom added the status: needs review label Jun 28, 2016

NelleV added the Documentation label Jun 28, 2016

tacaswell added this to the 2.1 (next point release) milestone Jun 28, 2016

NelleV added status: needs patch status: needs revision and removed status: needs patch status: needs revision labels Jun 29, 2016

QuLogic reviewed Jun 29, 2016
View reviewed changes

NelleV assigned jswhit Jun 29, 2016

jankatins reviewed Jun 30, 2016
View reviewed changes

NelleV added 8 commits September 8, 2016 09:20

ENH doc is now built with the new sphinx build

11de488

Instead of relying on make.py which is the antiquated way of building sphinx documentation, the build now relies on sphinx-build through a makefile (or make.bat for windows). closes #5798

ENH Activated warnings-to-error sphinx option

9d4bec6

ENH added a Makefile action to build LR images doc

32906a8

- typing make html-small-images now generates low resolution images in the documentation. - makefile now creates symlinks and others

DOC documents the new way of building sphinx-doc

ed05541

FIX travis now builds docs with new makefile

ab956b1

ENH doc uses symbolic link insteal of relying on copying

c7e056f

FIX documentation nitpick

c6432b4

tacaswell reviewed Sep 8, 2016
View reviewed changes

NelleV closed this Oct 17, 2016

mdboom removed the status: needs review label Oct 17, 2016

phobson mentioned this pull request Jan 13, 2017

Beautified frontpage plots and two pylab examples #7740

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ENH doc is now built with the new sphinx build #6663

ENH doc is now built with the new sphinx build #6663

NelleV commented Jun 28, 2016 •

edited

Loading

NelleV commented Jun 28, 2016

jenshnielsen commented Jun 28, 2016 •

edited

Loading

QuLogic Jun 29, 2016

tacaswell Jun 29, 2016

NelleV Jun 29, 2016

tacaswell commented Jun 29, 2016

NelleV commented Jun 29, 2016

tacaswell commented Jun 29, 2016

jankatins commented Jun 30, 2016

jankatins Jun 30, 2016

NelleV commented Jul 4, 2016

jankatins commented Jul 5, 2016 •

edited

Loading

jankatins commented Jul 5, 2016

NelleV commented Sep 7, 2016

tacaswell Sep 8, 2016

NelleV commented Sep 14, 2016

QuLogic commented Sep 14, 2016

NelleV commented Sep 14, 2016

NelleV commented Oct 17, 2016

		@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."


		prepare: mpl_examples mpl_toolkits/axes_grid1/examples \

		@@ -0,0 +1,333 @@
		.. The source of this document is INSTALL. During the doc build process,

ENH doc is now built with the new sphinx build #6663

ENH doc is now built with the new sphinx build #6663

Conversation

NelleV commented Jun 28, 2016 • edited Loading

NelleV commented Jun 28, 2016

jenshnielsen commented Jun 28, 2016 • edited Loading

QuLogic Jun 29, 2016

Choose a reason for hiding this comment

tacaswell Jun 29, 2016

Choose a reason for hiding this comment

NelleV Jun 29, 2016

Choose a reason for hiding this comment

tacaswell commented Jun 29, 2016

NelleV commented Jun 29, 2016

tacaswell commented Jun 29, 2016

jankatins commented Jun 30, 2016

jankatins Jun 30, 2016

Choose a reason for hiding this comment

NelleV commented Jul 4, 2016

jankatins commented Jul 5, 2016 • edited Loading

jankatins commented Jul 5, 2016

NelleV commented Sep 7, 2016

tacaswell Sep 8, 2016

Choose a reason for hiding this comment

NelleV commented Sep 14, 2016

QuLogic commented Sep 14, 2016

NelleV commented Sep 14, 2016

NelleV commented Oct 17, 2016

NelleV commented Jun 28, 2016 •

edited

Loading

jenshnielsen commented Jun 28, 2016 •

edited

Loading

jankatins commented Jul 5, 2016 •

edited

Loading