DOC: Move FITS example gallery to FAQ #16194

pllim · 2024-03-13T16:58:12Z

Description

This pull request is to stop using example gallery for io.fits as discussed in #16175 (comment) .

Rendered HTML: https://astropy--16194.org.readthedocs.build/en/16194/

Partially addressed the following issues:

Pro: Faster doc build. Less reliance on sphinx-gallery. One step closer to getting rid of defunct Examples Gallery.

Con: The code snippet won't be indirectly tested during example gallery building. I did not unleash doctest on them because they heavily rely on remote data and one even creates "out of memory" file.

By checking this box, the PR author has requested that maintainers do NOT use the "Squash and Merge" button. Maintainers should respect this when possible; however, the final decision is at the discretion of the maintainer that merges the PR.

github-actions · 2024-03-13T16:58:41Z

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.

Do the proposed changes actually accomplish desired goals?
Do the proposed changes follow the Astropy coding guidelines?
Are tests added/updated as required? If so, do they follow the Astropy testing guidelines?
Are docs added/updated as required? If so, do they follow the Astropy documentation guidelines?
Is rebase and/or squash necessary? If so, please provide the author with appropriate instructions. Also see instructions for rebase and squash.
Did the CI pass? If no, are the failures related? If you need to run daily and weekly cron jobs as part of the PR, please apply the "Extra CI" label. Codestyle issues can be fixed by the bot.
Is a change log needed? If yes, did the change log check pass? If no, add the "no-changelog-entry-needed" label. If this is a manual backport, use the "skip-changelog-checks" label unless special changelog handling is necessary.
Is this a big PR that makes a "What's new?" entry worthwhile and if so, is (1) a "what's new" entry included in this PR and (2) the "whatsnew-needed" label applied?
At the time of adding the milestone, if the milestone set requires a backport to release branch(es), apply the appropriate "backport-X.Y.x" label(s) before merge.

github-actions · 2024-03-13T16:58:44Z

👋 Thank you for your draft pull request! Do you know that you can use [ci skip] or [skip ci] in your commit messages to skip running continuous integration tests until you are ready?

pllim · 2024-03-13T17:00:41Z

examples/io/plot_fits-image.py

Note: I removed the astropy matplotlib style in the FAQ version of this example following discussion in #16053 (comment)

pllim · 2024-03-13T17:01:39Z

examples/io/split-jpeg-to-fits.py

This example isn't link from anywhere else in the doc, so I removed it altogether. I really don't see any need of example to turn RGB to FITS. I have only see real life usage of the other way around. Not sure why this was added.

saimn

Thanks @pllim for moving forward on this :), I tried some time ago and forgot about it.
Some of the examples should be merged (and simplified) in the corresponding doc page, I can try to do that.

docs/io/fits/appendix/faq.rst

saimn · 2024-03-13T20:51:56Z

docs/io/fits/appendix/faq.rst

@@ -269,11 +374,144 @@ this FAQ might provide an example of how to do this.
 .. _PyTables: http://www.pytables.org/


+.. _sphx_glr_generated_examples_io_create-mef.py:
+
 How do I create a multi-extension FITS file from scratch?
 ---------------------------------------------------------



I think we can remove this example/section, there is one already on the index page that provides the same information (could be improved a bit, at least mentioned the MEF acronym, I have an old commit for that that I can push here: saimn@705ccb4).

saimn · 2024-03-13T20:56:28Z

docs/io/fits/appendix/faq.rst

+
+How do I access data stored as a table in a multi-extension FITS file?
+----------------------------------------------------------------------
+


Not sure if we already have an example for Table.read but if not this should go somewhere else. I will try to find where later ;)

I tried to find one but nothing "beginner friendly" popped up. 😬

I think I finally found it: https://docs.astropy.org/en/stable/io/unified.html#fits

saimn · 2024-03-13T21:00:07Z

docs/io/fits/appendix/faq.rst

+.. _sphx_glr_generated_examples_io_plot_fits-image.py:
+
+How do I read and plot an image from a FITS file?
+-------------------------------------------------


I was going to say this one is useless but seems we don't have an example with imshow ! Might be useful to add at the beginning of the "image" page.

saimn · 2024-03-13T21:03:02Z

docs/io/fits/appendix/faq.rst

+.. _sphx_glr_generated_examples_io_modify-fits-header.py:
+
+How do I edit a FITS header?
+----------------------------


Same as above, missing info should go to the "headers" page.

pllim · 2024-03-13T22:49:24Z

Some of the examples should be merged (and simplified) in the corresponding doc page, I can try to do that.

Is your plan to push commit to my PR? If so, we should coordinate.

Thanks for the quick review!

Co-authored-by: Simon Conseil <contact@saimon.org>

pllim · 2024-03-14T16:48:24Z

@saimn , I accepted your one suggestion (and also applied it to the other entry with similar os.remove snippet).

It sounds like you want to handle the rest of your comments as direct push to this PR? If so, feel free now. Thanks!

saimn · 2024-03-15T08:34:46Z

@pllim - Ok thanks. I can PR to your fork if you prefer. For now I have one commit for the MEF section and I need to find a better place for the other items.

pllim · 2024-03-15T18:18:17Z

I can PR to your fork if you prefer

Naw. Just push to my branch here. It is simpler that way. I have no plans to add anymore commits if we have the understanding that you are taking over. Thanks!

pllim · 2024-03-18T17:18:59Z

@saimn , I cannot approve my own PR, so feel free to approve when you are done. Thanks!

saimn · 2024-03-18T18:04:38Z

@pllim - I think I'm done. Approving so you can merge if you're happy with the changes :)

pllim

Thanks, @saimn ! Just a comment and a question. 😉

pllim · 2024-03-18T18:20:28Z

docs/io/fits/usage/image.rst

+Generally the image information is located in the Primary HDU, also known
+as extension 0. Here, we use :func:`astropy.io.fits.getdata` to read the image
+data from this first extension using the keyword argument ``ext=0`` and obtain
+a 2D nupy array that we can visualize with matplotlib:


Suggested change

a 2D nupy array that we can visualize with matplotlib:

a 2D numpy array that we can visualize with matplotlib:

pllim · 2024-03-18T18:21:41Z

docs/io/fits/usage/image.rst

+    from astropy.io import fits
+    from astropy.utils.data import get_pkg_data_filename
+
+    image_file = get_pkg_data_filename("tutorials/FITS-images/HorseHead.fits")


Do we really need remote data access just to show people how to imshow? 👀

We cannot reuse one of these? https://github.com/astropy/astropy/tree/main/astropy/io/fits/tests/data

Yeah, I hesitated about this one... I included it only because there was an example to migrate, and no alternative in io/fits/tests/data. It's nice showing an image in the docs but not really necessary, I'm fine with removing it.

Since there were PRs to speed up doc build, maybe we shouldn't regress by adding a remote data plot that would render all the time? Let's remove if you don't mind. Thanks!

pllim · 2024-03-18T21:07:50Z

Thanks for the improvements, @saimn !

pllim added Docs Refactoring no-changelog-entry-needed labels Mar 13, 2024

pllim added this to the v6.1.0 milestone Mar 13, 2024

github-actions bot added io.fits installation labels Mar 13, 2024

pllim mentioned this pull request Mar 13, 2024

DOC: Move sphinx-gallery examples out of core (this) repository #16175

Open

pllim commented Mar 13, 2024

View reviewed changes

pllim marked this pull request as ready for review March 13, 2024 17:34

pllim requested a review from saimn as a code owner March 13, 2024 17:34

saimn reviewed Mar 13, 2024

View reviewed changes

pllim and others added 2 commits March 14, 2024 12:37

DOC: Move FITS example gallery to FAQ

abb5277

DOC: Remove os.remove in FITS FAQ.

bfbe8d7

Co-authored-by: Simon Conseil <contact@saimon.org>

pllim force-pushed the exorcise-fits-example-gallery branch from cb67fa2 to bfbe8d7 Compare March 14, 2024 16:47

improve the MEF section in docs and remove old example

43b9c7a

saimn added 4 commits March 15, 2024 23:08

improve unified io section and remove chandra example [docs only]

469162e

move plot example to usage/image.rst

eb5a7a0

fix chandra example

0558b35

improve convenience section

5faf6ed

saimn approved these changes Mar 18, 2024

View reviewed changes

pllim commented Mar 18, 2024

View reviewed changes

remove plot example

af36106

pllim merged commit 82532c8 into astropy:main Mar 18, 2024
24 of 27 checks passed

pllim deleted the exorcise-fits-example-gallery branch March 18, 2024 21:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: Move FITS example gallery to FAQ #16194

DOC: Move FITS example gallery to FAQ #16194

pllim commented Mar 13, 2024 •

edited

github-actions bot commented Mar 13, 2024

github-actions bot commented Mar 13, 2024

pllim Mar 13, 2024 •

edited

pllim Mar 13, 2024

saimn left a comment

saimn Mar 13, 2024

saimn Mar 13, 2024

pllim Mar 13, 2024

pllim Mar 14, 2024

saimn Mar 13, 2024

saimn Mar 13, 2024

pllim commented Mar 13, 2024

pllim commented Mar 14, 2024

saimn commented Mar 15, 2024

pllim commented Mar 15, 2024

pllim commented Mar 18, 2024

saimn commented Mar 18, 2024

pllim left a comment

pllim Mar 18, 2024

pllim Mar 18, 2024

saimn Mar 18, 2024

pllim Mar 18, 2024

saimn Mar 18, 2024

pllim commented Mar 18, 2024


		How do I access data stored as a table in a multi-extension FITS file?
		----------------------------------------------------------------------

	a 2D nupy array that we can visualize with matplotlib:
	a 2D numpy array that we can visualize with matplotlib:

DOC: Move FITS example gallery to FAQ #16194

DOC: Move FITS example gallery to FAQ #16194

Conversation

pllim commented Mar 13, 2024 • edited

Description

github-actions bot commented Mar 13, 2024

github-actions bot commented Mar 13, 2024

pllim Mar 13, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

saimn left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pllim commented Mar 13, 2024

pllim commented Mar 14, 2024

saimn commented Mar 15, 2024

pllim commented Mar 15, 2024

pllim commented Mar 18, 2024

saimn commented Mar 18, 2024

pllim left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pllim commented Mar 18, 2024

pllim commented Mar 13, 2024 •

edited

pllim Mar 13, 2024 •

edited