Repository navigation
Conversation
requirements in the docs build, so long as the meet the minimum requirements. This will be needed especially for development/testing of our own packages, such as sphinx-astropy. Fixes astropy#11838 [skip ci]
It's marked :orphan: since it's not directly included in the main ToC, but is still linked to from the front page. It includes its own ToC for documents under developer/ and a couple others.
not much rhyme or reason to the specific ordering; I thought it made sense as a more granular alternative to "Major Release History". Just as long as it's on the front page, as I'm in the habit of going to projects' docs and searching the page for "changelog", and ours is one of the best I've ever seen :-)
| :orphan: | ||
|
|
||
| *********************** | ||
| Contributing to Astropy |
There was a problem hiding this comment.
Since you invited bikeshedding... 😄 This feels like it should just be Developer Documentation, following the section title in the main index page. Contributing to Astropy is a much broader thing (https://www.astropy.org/contribute.html), while the docs here are really focused on developing code for the astropy core package.
There was a problem hiding this comment.
That's why this is still a WIP. My next step that I've been working on is making the page (at least at the top level) a little more generic. My inspiration here is matplotlib (which incidentally does still name itself "The Developer's Guide"): https://matplotlib.org/stable/devel/index.html
But I'm happy to revisit this once the PR is further along.
| love contributions! Astropy is open source, built on open source, and we'd | ||
| love to have in our community. | ||
|
|
||
| For the time being, please see our `CONTRIBUTING.md |
There was a problem hiding this comment.
As above, my take is to have this section focused on writing code and docs, so skip the generic "contributing" thing, which is well-covered in other places.
| maintainers on how to work the Astropy repository for submitting | ||
| documentation and code changes. | ||
|
|
||
| For the guiding vision of this process and the project |
There was a problem hiding this comment.
I don't think this is needed in this context.
There was a problem hiding this comment.
I don't know. It used to be on the main index page of the docs. I could maybe move it back there--I kind of agree it doesn't belong here.
| <https://github.com/astropy/astropy/blob/main/CONTRIBUTING.md>`_ document | ||
| for an overview of ways you can contribute to Astropy. The rest of this | ||
| document is focused specifically on documentation for contributors and | ||
| maintainers on how to work the Astropy repository for submitting |
There was a problem hiding this comment.
"how to work the Astropy repository" seems a bit awkward and narrowly focused. Overall there is an end to end process for developing new code or doc updates which includes creating a development environment, working with git and GitHub, making local updates, running tests, and working through the GitHub and astropy PR process.
There was a problem hiding this comment.
I agree, and I struggled a bit on this wording. I believe it encapsulates all of that (where "repository" is implying both on GitHub and working with the code locally). But I can try to rethink this. Any suggestions? Or maybe, instead of trying to be overly concise, I can replace this with a list like you just wrote "creating a development environment, working with git and GitHub, making local updates, running tests, and working through the GitHub and astropy PR process"
There was a problem hiding this comment.
Replacing with the list would work. 😄
mhvk
left a comment
mhvk
left a comment
There was a problem hiding this comment.
Only had a quick look, but U share @taldcroft's notion that it makes sense to just focus on direct contributions to the astropy git, i.e., code & docs, since other ways of contribution are already well covered on the general astropy web page.
| There are some additional tools, mostly of use for maintainers, in the | ||
| `astropy/astropy-procedures repository | ||
| <https://github.com/astropy/astropy-procedures>`__. | ||
| The developer/contributor documentation has been moved to its own page at |
There was a problem hiding this comment.
While the previous list was definitely too long, I would love to keep the main links on this page; I use these frequently!
There was a problem hiding this comment.
From now on you would go to docs.astropy.org/en/latest/development
There was a problem hiding this comment.
From now on you would go to docs.astropy.org/en/latest/development
My point was that I frequently used the general docs.astropy.org page and could jump immediately to the page of interest; now I need another step. To me, the original design makes sense - have links to important pieces of each category; the only problem was that small/unimportant pieces had accumulated.
|
@embray , a note from @eblur about the PR checklist that would be in scope here maybe, "I understand that this check list is intended mainly for reviewers, but would be very helpful to new developers if a link to this checklist could be provided somewhere in the documentation for contributing to Astropy. This will help them make sure they have done everything necessary and cut down on the number of comments / revisions requested." |
|
Hi humans 👋 - this pull request hasn't had any new commits for approximately 4 months. I plan to close this in 30 days if the pull request doesn't have any new commits by then. In lieu of a stalled pull request, please consider closing this and open an issue instead if a reminder is needed to revisit in the future. Maintainers may also choose to add keep-open label to keep this PR open but it is discouraged unless absolutely necessary. If this PR still needs to be reviewed, as an author, you can rebase it to reset the clock. If you believe I commented on this pull request incorrectly, please report this here. |
|
I'm going to close this pull request as per my previous message. If you think what is being added/fixed here is still important, please remember to open an issue to keep track of it. Thanks! If this is the first time I am commenting on this issue, or if you believe I closed this issue incorrectly, please report this here. |
This PR is to address #11621.
It starts by adding a new landing/index page for the developer docs, which is linked to from the main index page. It's also now titled "Contributing to Astropy" though this can be bikeshedded.
Still several other bullet points from #11621 to work on, in particular adding a new, easier to follow quick-start guide for making a contribution through the repository/GitHub.