I haven't been able to use yet all the cool features of sphinx-gallery. One of them is the possibility to link automatically to examples in the API reference, see http://sphinx-gallery.readthedocs.io/en/latest/advanced_configuration.html#references-to-examples

All projects using this feature of sphinx-gallery (such as nilearn, mne-python) seem to rely on templates for the generation of their API. In scikit-image, we use apigen.py, but not templates. Before hacking apigen.py, I'd like to get feedback from sphinx experts: what are the pros and cons of using either apigen.py or templates?

@scikit-image/core I know that this PR is breaking Travis, but I would still welcome comments, in particular about the API generation (see my previous comment). Thanks!

Regarding Travis' cause of failure, I've opened an issue (sphinx-gallery/sphinx-gallery#120) on sphinx-gallery, since the error is weird: the image file is mentioned as "not readable", but is correctly included in the html page...

Any idea about this weird error?

This is a great step forward, thanks Emmanuelle! Can you explain what you
mean by "template"? At the moment, apigen.py just imports scikit-image and
traverses the submodule tree, figuring which functions to autodoc, so that
we don't have to keep an index up to date when new functionality is added.

On Wed, 18 May 2016 at 22:41 Emmanuelle Gouillart [email protected]
wrote:

Regarding Travis' cause of failure, I've opened an issue (
sphinx-gallery/sphinx-gallery#120
sphinx-gallery/sphinx-gallery#120) on
sphinx-gallery, since the error is weird: the image file is mentioned as
"not readable", but is correctly included in the html page...

Any idea about this weird error?

—
You are receiving this because you are on a team that was mentioned.

Reply to this email directly or view it on GitHub
#2078 (comment)

Yeah, I'm super excited about it :-). Having the little pop-up when hovering over thumbnails, or links to the API in the examples, is really cool. I just have to solve this sphinx warning/error now :-/.

About templates, what I meant is that (from what I understand), the content of API is generated by apigen.ApiDocWriter.generate_api_doc (am I wrong maybe?) when make calls python tools/build_modref_templates.py. generate_api_doc builds a rst string for the objects of a given module.

On the other hand, other packages (sphinx-gallery, nilearn) use templates as in https://raw.githubusercontent.com/nilearn/nilearn/master/doc/templates/function.rst
In particular, .. include:: {{module}}.{{objname}}.examples is used to include a small gallery of thumbnails of examples using a given function.

Travis is happy now, so I would be happy to get reviews :-).

@sciunto @jni all the files in ext/sphinx-gallery are directly copied from the sphinx_gallery package. Any changes that we make should be submitted as pull requests to the original package.

@sciunto of course, sorry. Worth trying to run your scanner on 0.11 then ( IMO :) ).

@emmanuelle sorry for attacking your patience 😃. I've added just a couple of concluding remarks.

@soupault no worries, thank you for the additional review. I removed the commented lines. About the missing spaces, it's some sphinx / sphinx-gallery magic: the layout is broken if I add the spaces. Maybe someone else can figure out if this can be improved. At the moment I'm in the middle of a 24/7 synchrotron campaign, so catching up with PRs is not easy. I let you guys decide if it can be merged as such.

@emmanuelle this builds and works fine for me https://gist.github.com/soupault/170e3065384431ae438e3793ac185fc2 . You have whitespaces after # for any other example, haven't you?

If you can improve this, it's perfect, but I have no time to fix it in the next few days (experiments running 24/7). Could you please submit a pull request to my branch, or if the PR can be merged with this minor style problem, file a separate PR later on? Thanks!

@emmanuelle I understood. Examples will need an extra review anyways, for me it is a no blocker.

I think the PR is finalized in it's essential part. As we have 👍 from @sciunto and several new PRs are starting to depend on this, I'm going for a merge.

@emmanuelle thank you a lot for this awesome work, and sorry again for any offense made! 🍷

@emmanuelle could you squash the commits, please? It is not possible to do this via GitHub interface ('Not enabled for this repository' 😕 )

@soupault I squashed most commits together, I only left the most important ones at the beginning because it may be important to keep a bit of granularity for an important move.

@emmanuelle Build fails on OS X.
Maybe worth squashing also 94d051c and d998e7e as the former is performing files' renaming while the latter is undoing it.

It's a latex problem

�[31;01mWarning, treated as error:�[39;49;00m

WARNING: display latex '\\sqrt{2}sigma': latex exited with error

[stdout]

This is pdfTeX, Version 3.14159265-2.6-1.40.17 (TeX Live 2016) (preloaded format=latex)

 restricted \write18 enabled.

entering extended mode

(./math.tex

LaTeX2e <2016/03/31>

Babel <3.9r> and hyphenation patterns for 22 language(s) loaded.

(/usr/local/texlive/2016basic/texmf-dist/tex/latex/base/article.cls

Document Class: article 2014/09/29 v1.4h Standard LaTeX document class

(/usr/local/texlive/2016basic/texmf-dist/tex/latex/base/size12.clo))

(/usr/local/texlive/2016basic/texmf-dist/tex/latex/base/inputenc.sty



! LaTeX Error: File `utf8x.def' not found.



Type X to quit or <RETURN> to proceed,

or enter new name. (Default extension: def)



Enter file name: 

! Emergency stop.

<read *> 



l.158 \endinput

               ^^M

No pages of output.

Transcript written on math.log.

@soupault Looks like it's travis. Same problem here #2129

This is passing now.
Builds on OS X started to fail 2 days ago, not sure that is the cause... Let's give a life to this PR and then investigate that issue.

😨

Thank you !!!

This was a massive amount of work; thank you so much @emmanuelle and @soupault for diligent reviewing.

Quick question: is this kind of output expected?

plotting code blocks in ../examples/transform/plot_seam_carving.py
 - time elapsed : 0.12 sec
plotting code blocks in ../examples/transform/plot_seam_carving.py
 - time elapsed : 0.12 sec
plotting code blocks in ../examples/transform/plot_seam_carving.py
 - time elapsed : 1.2 sec
plotting code blocks in ../examples/transform/plot_seam_carving.py
 - time elapsed : 0.11 sec
plotting code blocks in ../examples/transform/plot_seam_carving.py

Yes, this output comes from sphinx_gallery. It can be useful to detect examples that take a lot of time to build. If you think that this is too verbose, we could submit a PR to sphinx_gallery so that this output can be optional only.

@soupault do you mean that building the doc (make html) is failing for you on OS X?

@emmanuelle no, not for me. There were some issues with our OS X Travis build (actually, I think that was Travis bug). See #2078 (comment) for the error message.