Developer documentation overhaul by taldcroft · Pull Request #16561 · astropy/astropy

taldcroft · 2024-06-14T01:18:17Z

Description

This pull request is to make the developer documentation more accessible to newcomers and more useable by maintainers. The current docs contain a lot of information but are not well-organized and contain a lot of repetition.

It reflects an approach that sometimes "less is more", so some material was cut (notably detailed documentation on how to use two virtualenv managers), but for the most part it keeps all substantive material while cutting repetitions.

There are a lot of commits and most of them are useless individually, so this should definitely be squash-merged. There are a couple of commits that could be controversial and are meaningful.

Fixes #11621

See also:

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-06-14T01:18:44Z

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-06-14T01:18:47Z

👋 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?

neutrinoceros · 2024-06-14T06:13:17Z

Is there an issue for this??

I found two related issues:

Development docs reorganization #11621
Documentation for trying the development version of Astropy ignores virtual environments #11207
From your description, it sounds like this PR would maybe close the second one as "not planned" ?

taldcroft · 2024-06-14T10:02:31Z

RTD is now passing so you can look at the new docs.

hamogu · 2024-06-14T13:38:29Z

I can't put a comment on it because this line is not yet changed, but I would also do away with astropy.test in favor of recommending to run pytest directly (https://github.com/astropy/astropy/pull/16561/files#diff-3082c98617b79c67603d9ef61bad41ef94d24d19a948af26eb52ca8ace968a97L368). Keep it simple by recommending one and only one way of doing it and we have #16208 open to remove astropy.test() anyway.

taldcroft · 2024-06-14T18:05:23Z

I can't put a comment on it because this line is not yet changed, but I would also do away with astropy.test in favor of recommending to run pytest directly

I had not appreciated this was technically possible for an installed package. But definitely 👍 on removing astropy.test() from the docs, will do (in coordination with #16208).

mhvk

@taldcroft - so far, I've just gone over the new quickstart guide - which I like very much! But of course some comments (mostly small).

eerovaher

I had a look at the text that is present, I didn't think too much about what is missing but should be included.

taldcroft · 2024-06-19T19:36:18Z

Thanks for the comments folks! I got through many but not all of them, but I'll keep on plugging (hopefully over the next few days).

taldcroft · 2024-06-21T19:40:15Z

All -- I think that I have addressed or at least responded to every comment. I think this is in good enough shape now that I have made it a Pull Request (not draft).

neutrinoceros · 2024-06-24T07:13:28Z

I'm going to review this today. For now, I just want to put a note that #16601 revealed an oversight in our dev docs. Fetching tags is necessary to first build and test astropy locally, and the information is there, but isn't presented as something you should do from the get go when you're getting started. Maybe you've already addressed this point (in which case I'll come back and hide this reply), but I wanted to make sure we addressed it too as part of the overhaul.

neutrinoceros

Some general level questions:

why were some files from docs/development/workflow moved, but not all ?
why replacing git checkout with git switch everywhere ? (this is a genuine question, I learned git before git switch was a thing and never really bothered migrating my muscle memory)

taldcroft · 2024-06-25T17:06:25Z

@pllim - rebased!

dhomeier

Thanks for undertaking this, this should point new contributors to a much clearer path!
I just had time for reading through the quickstart and core workflow sections, only a few suggestions for potential improvements.

pllim

Here is the rest of my review. Since you said contents update largely is out of scope, I focused only on the stuff not inside development this time.

pllim · 2024-06-27T16:27:09Z

   index_getting_started
   index_user_docs
-   index_dev
+   development/index


I think there was a reason why we made the index at top level (index_dev) vs development/index but I don't remember why now. @saimn , do you remember?

Just going to xref #14867 here in case we need to revert this particular change in the future.

Co-authored-by: Derek Homeier <709020+dhomeier@users.noreply.github.com>

taldcroft · 2024-07-01T10:58:16Z

OK, I think I have addressed all review comments. There are some other PR's being blocked by this, so maybe it is time to merge this and start fresh with any other minor cleanups?

taldcroft · 2024-07-01T13:48:57Z

@pllim - are you OK with merging now? I see 👍 from a few others that have reviewed.

pllim · 2024-07-01T14:03:50Z

There is an edited comment from @dhomeier saying that git switch is experimental at #16561 (comment) . Should we be recommending experimental Git command?

pllim · 2024-07-01T14:19:24Z

devdeps failures are unrelated.

taldcroft · 2024-07-01T16:00:31Z

There is an edited comment from @dhomeier saying that git switch is experimental at #16561 (comment) . Should we be recommending experimental Git command?

Git switch was released in 2.23 almost 5 years ago. I'm not sure why they have not removed the "experimental" comment, but I don't think it is credible that they would now drop or make big changes to git switch.

pllim · 2024-07-01T16:06:39Z

Oh... ok then. Are you okay with "Squash and Merge"? 🚀

taldcroft · 2024-07-01T16:16:39Z

Oh... ok then. Are you okay with "Squash and Merge"? 🚀

For sure squash and merge. There is no value in all the intermediate commits and LOTS of churn!

pllim · 2024-07-01T16:24:44Z

Done. Thanks!!!

mhvk · 2024-07-02T07:00:19Z

Thanks! So nice to have clearer devdocs!!

* Remove coding guide info for emacs * Add a copy of pandas development docs * Add pandas-based development docs to index * Remove a codespell false positive * Remove {{header}} from pd-based docs * Replace pandas with astropy * Touch-ups on contributing.rst * Bring the pandas files into the main dev dir * Remove contributing different ways (superseded) * Remove non-applicable pandas content * Update git_edit_workflow_examples * Put tox into dev_all * Remove pandas contributing codebase * More tweaks to testing guide * First pass at the documentation guide * Remove pandas contributing_documentation * Remove pandas doc files part duex * Move git_resources out of workflow * Make one quickstart doc * Move the remaining bits from workflow dir * Remove building and virtual_pythons docs * Change target links to anonymous * Remove doc refs to `astropy.test()`; replace w/ pytest * Respond to review comments * Apply suggestions from code review Co-authored-by: Eero Vaher <eero.vaher@gmail.com> * Address more review comments * More comments; use git switch in non-maintainer docs * Fix typo in git switch command * Apply suggestions from code review Co-authored-by: Clément Robert <cr52@protonmail.com> Co-authored-by: P. L. Lim <2090236+pllim@users.noreply.github.com> * More updates and review comments * Add What's New and changelog entries * Update docs/development/quickstart.rst Co-authored-by: Derek Homeier <709020+dhomeier@users.noreply.github.com> * Address more review comments * Move is_development statement for clarity * Other various updated related to dev docs --------- Co-authored-by: Eero Vaher <eero.vaher@gmail.com> Co-authored-by: Clément Robert <cr52@protonmail.com> Co-authored-by: P. L. Lim <2090236+pllim@users.noreply.github.com> Co-authored-by: Derek Homeier <709020+dhomeier@users.noreply.github.com>

taldcroft requested a review from adrn June 14, 2024 01:18

github-actions Bot added testing Docs installation labels Jun 14, 2024

taldcroft added the no-changelog-entry-needed label Jun 14, 2024

pllim added this to the v7.0.0 milestone Jun 14, 2024

taldcroft mentioned this pull request Jun 14, 2024

MAINT: Remove astropy.test(), should use pytest directly #16208

Closed

jeffjennings mentioned this pull request Jun 14, 2024

Add type annotations to stats subpackage #16562

Merged

1 task

taldcroft mentioned this pull request Jun 14, 2024

Update policy and implementation for changelog entries #16569

Open

mhvk reviewed Jun 17, 2024

View reviewed changes

eerovaher reviewed Jun 17, 2024

View reviewed changes

taldcroft force-pushed the doc-dev-quickstart branch from a624a4c to 1a590aa Compare June 21, 2024 19:25

taldcroft marked this pull request as ready for review June 21, 2024 19:25

taldcroft requested review from eerovaher, hamogu and mhvk June 21, 2024 19:38

neutrinoceros reviewed Jun 24, 2024

View reviewed changes

This comment was marked as resolved.

Sign in to view

taldcroft force-pushed the doc-dev-quickstart branch from 3621a4a to 33d8966 Compare June 25, 2024 16:56

pllim mentioned this pull request Jun 25, 2024

DOC: Remove astropy-dev intersphinx (try 2) #16612

Closed

1 task

dhomeier approved these changes Jun 27, 2024

View reviewed changes

Comment thread docs/development/quickstart.rst Outdated

Comment thread docs/development/quickstart.rst Outdated

Comment thread docs/development/quickstart.rst Outdated

pllim reviewed Jun 27, 2024

View reviewed changes

taldcroft and others added 3 commits June 30, 2024 08:45

Update docs/development/quickstart.rst [ci skip]

8da1dab

Co-authored-by: Derek Homeier <709020+dhomeier@users.noreply.github.com>

Address more review comments [ci skip]

1e42733

Move is_development statement for clarity

9cd1ea5

pllim merged commit 875b80c into astropy:main Jul 1, 2024

pllim mentioned this pull request Jul 1, 2024

DOC: Fix What's New for 7.0 and bad intersphinx, remove astropy-dev tag #16646

Merged

1 task

taldcroft mentioned this pull request Jul 2, 2024

Revert move of index_dev.rst to development/index.rst #16657

Merged

1 task

pllim mentioned this pull request Jul 8, 2024

DOC: Fix broken links from dev docs re-organization #16689

Merged

1 task

This was referenced Jul 23, 2024

Roadmap 2024 astropy/astropy-project#433

Merged

v6.1.2 has RTD warning and failed doc build #16764

Closed

neutrinoceros mentioned this pull request Jul 29, 2024

DEP: refactored out an undeclared runtime dependency on setuptools karllark/dust_extinction#215

Merged

pllim mentioned this pull request Aug 23, 2024

DOC: Link developer install instructions is missing and results in a 404 #16871

Closed

dhomeier mentioned this pull request Oct 10, 2024

Fixing documentation and message template for adding new members astropy/astropy-project#447

Merged

pllim mentioned this pull request Oct 28, 2024

DOC: Copy-paste good stuff from scikit-learn contributing guide #10461

Closed

pllim mentioned this pull request Aug 25, 2025

DOC: "Install from source" section has wrong URL on stable but not latest #18552

Closed

Uh oh!

Uh oh!

Conversation

taldcroft commented Jun 14, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

github-actions Bot commented Jun 14, 2024

Uh oh!

github-actions Bot commented Jun 14, 2024

Uh oh!

neutrinoceros commented Jun 14, 2024

Uh oh!

taldcroft commented Jun 14, 2024

Uh oh!

hamogu commented Jun 14, 2024

Uh oh!

taldcroft commented Jun 14, 2024

Uh oh!

mhvk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

eerovaher left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

taldcroft commented Jun 19, 2024

Uh oh!

taldcroft commented Jun 21, 2024

Uh oh!

neutrinoceros commented Jun 24, 2024

Uh oh!

neutrinoceros left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as resolved.

taldcroft commented Jun 25, 2024

Uh oh!

dhomeier left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pllim left a comment

Choose a reason for hiding this comment

Uh oh!

pllim Jun 27, 2024

Choose a reason for hiding this comment

Uh oh!

pllim Jul 1, 2024

Choose a reason for hiding this comment

taldcroft commented Jun 14, 2024 •

edited

Loading