Skip to content

docs(dev): add meta docs on writing docs #18163

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

woodruffw
Copy link
Member

This adds some development-level docs on writing docs.

Note: this is an initial set; I'll follow up with more detailed sections on writing new sections, adding files, etc.

CC @Thespi-Brain @ewdurbin

@woodruffw woodruffw requested a review from a team as a code owner May 20, 2025 15:44
@woodruffw woodruffw self-assigned this May 20, 2025
@woodruffw woodruffw added documentation developer experience Anything that improves the experience for Warehouse devs labels May 20, 2025
Copy link
Member

@miketheman miketheman left a comment

Choose a reason for hiding this comment

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

I am generally in favor of this, thanks for getting it started!

One nit inline.

How does this page relate to other documentation stuff like https://github.com/pypi/warehouse/blob/51ffd8ff87d763509486ac3cd03e07cdb92be693/docs/dev/development/getting-started.rst#building-documentation ? (that section is stale too, since we don't do Python 3.8 any more, and everything is kinda sorta self-contained)

=======================

The developer documentation is hosted at `warehouse.pypa.io`_. It's written in
`reStructuredText`_ and built using `Sphinx`_.
Copy link
Member

Choose a reason for hiding this comment

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

We allow Markdown as well, by including myst_parser. See https://github.com/pypi/warehouse/blob/51ffd8ff87d763509486ac3cd03e07cdb92be693/docs/dev/architecture.md for one example.

@woodruffw
Copy link
Member Author

How does this page relate to other documentation stuff like 51ffd8f/docs/dev/development/getting-started.rst#building-documentation ? (that section is stale too, since we don't do Python 3.8 any more, and everything is kinda sorta self-contained)

Huh, I completely missed that section! Unless you feel like it's worth keeping, perhaps we could remove that and break the doc documentation out fully? IMO there will be enough here for it to need its own hierarchy.

@woodruffw woodruffw requested a review from miketheman May 20, 2025 20:38
Copy link
Member

@miketheman miketheman left a comment

Choose a reason for hiding this comment

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

Good to go!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
developer experience Anything that improves the experience for Warehouse devs documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants