Skip to content

Add documentation for LaTeX formatted tables with units - #17627

Merged
pllim merged 2 commits into
astropy:mainfrom
hamogu:fix_14853
Jan 11, 2025
Merged

pllim merged 2 commits into
astropy:mainfrom
hamogu:fix_14853

Conversation

@hamogu

@hamogu hamogu commented Jan 11, 2025

Copy link
Copy Markdown
Member

Description

This pull request adds documentation that explicitly explaines why LaTeX tables are written with units, but reading the units in LaTeX tables is out of scope. An example for ignoring a lines with units in the table is added.

Fixes #14853

  • 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

Copy link
Copy Markdown
Contributor

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.

@hamogu hamogu added this to the v7.0.1 milestone Jan 11, 2025

@hamogu hamogu left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I looked for a while what the best location for that added documentation would be. It makes the docstring pretty long in the location where it is now. However, I found that throughout the docs we always link to this docstring when the talk about reading and writing LaTeX tables, so I think this is a natural place where people can find it. It is LaTeX specific as written, so I think it's better here then on a general "tips and ticks" pages (that we don't have like that anyway). Alternatively, one could move it down below the description of the keywords.

@mhvk mhvk left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice! Some suggestions inline for avoiding having to spell out the table in the second example.

Also, I wondered a bit about how people would find this, but found that both google and duckduckgo have the docs for this class as one of the first entries when one searches "astropy write latex table". And of course t.write.help("ascii.latex") does too, though I wonder how many people would know to try that...

Comment thread astropy/io/ascii/latex.py Outdated
Comment thread astropy/io/ascii/latex.py Outdated
@hamogu

hamogu commented Jan 11, 2025

Copy link
Copy Markdown
Member Author

And of course t.write.help("ascii.latex") does too, though I wonder how many people would know to try that...

I only discovered that while writing this PR and I've been an io.ascii maintainer for close to a decade... but I frequently look at this table and then click on the linked classes there. However, search engines are probably the most common entry point to our docs.

@mhvk mhvk left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Super, thanks!

@pllim
pllim merged commit 3995bc1 into astropy:main Jan 11, 2025
meeseeksmachine pushed a commit to meeseeksmachine/astropy that referenced this pull request Jan 11, 2025
pllim added a commit that referenced this pull request Jan 11, 2025
…627-on-v7.0.x

Backport PR #17627 on branch v7.0.x (Add documentation for LaTeX formatted tables with units)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Latex tables with units don't read properly

3 participants