Repository navigation
Minor improvements to mechanics of example gallery - #4924
Conversation
|
(the travis failure is a red herring due to #4908 - just fixed it in master) |
| 'mod_example_dir': 'generated/modules', # path to store the module using example template | ||
| 'filename_pattern': '^((?!skip_).)*$', # execute all examples except those that start with "skip_" | ||
| 'examples_dirs': '..{}examples'.format(os.sep), # path to the examples scripts | ||
| 'gallery_dirs': 'generated/examples', # path to save gallery generated examples |
There was a problem hiding this comment.
What about putting it into the same place the rest of the generated docs, e.g. docs/_build/generated? Although I can see similarity with docs/api that also contains generated stuff and doesn't live in the build directory (although I think it also should).
There was a problem hiding this comment.
I recently changed this for SunPy so that it results in a nice URL for the gallery: http://docs.sunpy.org/en/latest/gallery/ which is maybe something to think about.
There was a problem hiding this comment.
@bsipocz - I thought the same at first, but decided not because that yields the final HTML urls as "docs.astropy.org/en/stable/_build/generated/whatever.html" which is rather ugly and reveals "implementation details" in the final product.
@Cadair - I could also change it just gallery (or better yet examples, because I think "gallery" is a less-clear term for this... gallery of what?), but that then means that the sphinx command has to include gallery/example. I think it's better to be consistent and put all generated things in generated, so that poor users who don't know sphinx very well can tell that that's where the generated things show up. (One could imagine also moving the API to generated/api... But my thinking is that there are already lots of things on the web using the docs.astropy.org/en/stable/api/... URL, so it's better to maintain backwards compatibility)
There was a problem hiding this comment.
Fair enough, I share the preference of having cleaner, nicer URLs, and I didn't think about it when wrote the comment.
|
Oh, and @Cadair - one thing you comment above implies is that |
|
@eteq yes that's true, it will not. I do like the idea of having a nice URL for the examples gallery. I think a little pain for the developers is worth it for the end user. |
|
@Cadair - well, it's not just a "little pain for the developers", it's a standard location to put generated things in to allow other ideas like Also I think it's important for advanced users/novice devs who have reason to try to build the docs themselves. A very common confusion I see in sphinx is a misunderstanding about what is generated and what is "real" content. So this is a way to be a bit more transparent. But this is all driven by the fact that I don't really see |
|
👍 to not making |
|
@eteq 👍 nice! This seems like a sensible idea - thanks! |
|
(travis is a red herring - an unrelated problem in master) Had an out-of-band conversation with @Cadair and he agrees |
some of this is copied from astropy/astropy#4924
astrofrog
added
the
Affects-dev
Minor improvements to mechanics of example gallery
This PR makes two changes to the new example gallery.
docs/generated/<something>. I think this is more clear, and on top of that, it makes it easier to work cleanly with the-largument ofpython setup.py build_sphinx. Will issue a PR againstastropy_helpersshortly to close the loop on that. Does this re-organization sound ok to you, @adrn ?