Repository navigation
DOC: Get rid of sphinx-gallery and move coordinates examples - #17270
Conversation
|
Thank you for your contribution to Astropy! 🌌 This checklist is meant to remind the package maintainers who will review this pull request of some common things to look for.
|
|
👋 Thank you for your draft pull request! Do you know that you can use |
cbca789 to
053e81b
Compare
This comment was marked as resolved.
This comment was marked as resolved.
cafe6f3 to
9500d26
Compare
This comment was marked as resolved.
This comment was marked as resolved.
This seems reminiscent of similar issues we've had with how numpy and scipy's bundled c++ libraries cannot guarantee portability at the ulp level. Isn't this what |
9500d26 to
5cdcec8
Compare
d7bf0df to
d7af9f9
Compare
|
If the biggest problem with the Example Gallery is code rot then how is just moving things from there to the main narrative documentation supposed to help with that? |
As you might have noticed, they are run in doctest now. |
|
Why can't we simply include the example gallery in the doctests? |
|
There was already plenty of discussion on the example gallery. We wanted to get rid of it. |
|
But you are not getting rid of it, you are just moving it around. |
|
I mean, getting rid of the sphinx-gallery stuff. No one can agreed on where to move it to, so I just made a decision to put them in new page under coordinates docs. If you have ideas, please share. Thanks! |
|
If you think these examples are duplicate of certain sections already, we can absorb them into those sections too. There are too much materials under coordinates docs and I don't feel like reading all of them. |
beeddcf to
b78fb68
Compare
cmarmo
left a comment
cmarmo
left a comment
There was a problem hiding this comment.
Thanks! Everything good for me.
| curve: | ||
|
|
||
| >>> fig, axes = plt.subplots(1, 2, figsize=(12, 6)) | ||
| >>> _ = axes[0].plot(gc_rings.x.T, gc_rings.y.T, marker="None", linewidth=3) |
There was a problem hiding this comment.
Why are all these underscores needed? As a reader I find them distracting.
There was a problem hiding this comment.
doctest complains about output otherwise because they return objects. In notebook, you could add ; to suppress that but I am not sure about >>>. I find having to add so many # doctest: +IGNORE_OUTPUT tedious but that is another option. Other ideas welcome.
There was a problem hiding this comment.
This is user-facing documentation. The closer the examples are to what the users should write themselves the better. The # doctest: +IGNORE_OUTPUT instructions are not rendered in the HTML documentation, so they are a much better solution than the leading underscores.
There was a problem hiding this comment.
Yes, makes sense, I guess laziness is no excuse... 😆
adrn
left a comment
adrn
left a comment
There was a problem hiding this comment.
I still believe in the idea of the sphinx-gallery and think it can be used effectively (see, e.g., scikit-learn's example gallery). Is the main argument to remove it that "the examples haven't been updated in a while" or is it still causing issues for the docs build? An alternative could be to solicit new maintainers or effort into maintaining the existing gallery.
|
I am confused about why we would want to have these examples in |
b78fb68 to
6b02d93
Compare
|
@adrn , I agree that a gallery is very useful for visualization driven library and analysis like matplotlib and scikit-learn . But astropy is a collection of many sub-packages, most not visually driven. In the 10+ years of this gallery existing here, it only had a few examples from FITS and coordinates (https://docs.astropy.org/en/v5.3.4/generated/examples/). These examples are not doctest-ed (not to be confused with rendered) and sit forgotten in a corner of the source dir. As Eero pointed out, Learn Astropy is a better place to illustrated a many capabilities of astropy . This gallery just never really took off and cause maintenance headache from time to time (and some complains about accessing remote data in a surprising way). I think in this case, the cost outweighs the benefit. |
|
So, can I go ahead with this? If so, I will rebase. Otherwise, I don't want to waste time keeping it updated. Please advise. Thanks! |
|
FWIW, I agree with tossing the gallery. EDIT: especially since we're not actually losing any examples, just the way they are generated. Sphinx is annoying enough on its own! |
WIP: Still need to copy over the contents. [ci skip]
…ame. Co-authored-by: Adrian Price-Whelan <[email protected]>
Update pyproject to handle deps Revert nice print as suggested by astrofrog
Co-authored-by: Chiara Marmo <[email protected]> Co-authored-by: Marten van Kerkwijk <[email protected]>
Co-authored-by: Erik Tollerud <[email protected]> Co-authored-by: Kelle Cruz <[email protected]>
Co-authored-by: Adrian Price-Whelan <[email protected]> Co-authored-by: Erik Tollerud <[email protected]>
Co-authored-by: Adrian Price-Whelan <[email protected]>
because it is set globally in conftest.py so not sure why that did not get pick up locally
as suggested by cmarmo
as suggested by eerovaher
6b02d93 to
cc4b63f
Compare
|
Exotic archs and linkcheck failures are unrelated. |
|
@mhvk , thanks for your inputs! I have rebased it. Are you willing to do a final review? 🙏 🙇♀️ |
- removed astropy (see astropy/astropy#17270) - updated some project URLs - linked to the gallery (or one of them) instead of the top-level project site
Description
This pull request is to finally move away from sphinx-gallery and get rid of the Example Gallery that never really lived up to its full potential. One less dependency to worry about.
Also see #16194
TODO