Skip to content
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

docs: new and shiny storage limit docs #17716

Merged
merged 8 commits into from
Mar 11, 2025

Conversation

woodruffw
Copy link
Member

@woodruffw woodruffw commented Mar 5, 2025

This is my attempt to scaffold out a clean segue from the existing help.html to the newer mkdocs-managed user documentation, using #17702 as a testcase.

Key changes:

  • There's a new request.user_docs_url request method that makes it easy to route to user documentation pages, including specific anchors.
  • I've added /project-management/storage-limits/ with most of the file/project storage limit content from help.html, along with additional context/rendering niceties/screenshots.
  • I've added /project-management/yanking/ with the yanking content from help.html, along with a short user tutorial on yanking releases.
  • I've removed the original yanking and file/project storage limit sections from help.html and changed the endpoints/views that linked it to link to the new docs page instead.

Some open questions:

  • Is this a good idea at all? I think the newer user docs are easier to iterate on, but I don't know if it's worth the complexity of the new user_docs_url request method 😅
  • Does /project-management/ make sense as a hierarchy for these docs? Or should this be just a top level /storage-limits/ or similar, or something different?

See #17702.

Closes #9013.

Signed-off-by: William Woodruff <[email protected]>
Signed-off-by: William Woodruff <[email protected]>
@woodruffw
Copy link
Member Author

For reference, this is what the new storage limits docs look like with this PR:

image

@woodruffw woodruffw self-assigned this Mar 5, 2025
@@ -5,6 +5,8 @@ WAREHOUSE_ENV=development
WAREHOUSE_TOKEN=insecuretoken
WAREHOUSE_IP_SALT="insecure himalayan pink salt"

USERDOCS_DOMAIN="http://localhost:10000"
Copy link
Member Author

Choose a reason for hiding this comment

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

NB: This ensures that local deployments link to the local user docs build, rather than docs.pypi.org (which is otherwise the default).

@woodruffw woodruffw marked this pull request as ready for review March 5, 2025 23:00
@woodruffw woodruffw requested a review from a team as a code owner March 5, 2025 23:00
Signed-off-by: William Woodruff <[email protected]>
@di
Copy link
Member

di commented Mar 9, 2025

@woodruffw FYI, you need to rebuild translations here.

@woodruffw
Copy link
Member Author

@woodruffw FYI, you need to rebuild translations here.

Done!

@di di enabled auto-merge (squash) March 11, 2025 13:29
@di di merged commit aeb9ccd into pypi:main Mar 11, 2025
20 checks passed
@woodruffw woodruffw deleted the ww/docs-storage-limits branch March 11, 2025 13:54
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.

Cover "how do I delete my package/project?" in help docs
2 participants