gh-149902: Remove dead packaging docs link and add a new section for external resources#150030
Conversation
miameows
requested review from
AA-Turner,
StanFromIreland and
hugovk
as code owners
Documentation build overview
20 files changed ·
|
| </td></tr> | ||
| </table> | ||
|
|
||
| <p><strong>{% trans %}Other resources:{% endtrans %}</strong></p> |
There was a problem hiding this comment.
With this we'll have two "Other resources" sections, one in the sidebar and one here, why not add these to the existing one?
There was a problem hiding this comment.
The "Other resources" section also has two links to the deprecated Python wiki, maybe we should drop those and link to packaging.python.org and typing.python.org instead.
There was a problem hiding this comment.
Do we need both "Other resources" sections?
If yes, should they both contain the same things?
If not, which shall we remlve?
Perhaps the wiki books link could be replaced with
https://www.pythondiscord.com/resources/?type=book or https://pythonbooks.org/ ?
See also #148998 for more general wiki cleanup.
There was a problem hiding this comment.
I'm in favor of removing the other section if it links to outdated content
There was a problem hiding this comment.
I think the placement of this new section should be fairly prominent, considering it contains a link that was (indirectly) already featured front and center. I think it's helpful to have a "signpost" of sorts so users who do a web search for "Python documentation" can easily find related resources without having to look at the small text in the sidebar. I'm of the opinion that sidebars are for navigation of complex hierarchies, not holding content
There was a problem hiding this comment.
I agree that the sidebar is serving two purposes now which could be confusing. If straightening that out expands the scope too much, we can continue the discussion in a subsequent PR.
There was a problem hiding this comment.
@nedbat It should be fairly easy (famous last words) to get this sorted. I think we would just remove the sidebar and put the 3 non-wiki links in this section. That being said, it does expand the scope of this PR. Thoughts on merging this as-is (now that @hugovk's table -> list conversion is merged) and combining the sections in a subsequent PR?
Co-authored-by: Stan Ulbrych <stan@python.org>
Co-authored-by: Stan Ulbrych <stan@python.org>
|
I like the idea of separating out these sections on the front page. But I would really like to do something about the vertical alignment. Currently the two columns of each table are centered (as shown here on the left), but should be top-aligned (as shown here on the right): 
The table styling comes from the basic Sphinx theme, so I'm not sure what our options are. The fix is to use this CSS: .contentstable td {
vertical-align: top;
}(Firefox claims this will have no effect, but it does, it's how I made the corrected image). I'll make a PR into this branch using explicit style attributes in the HTML as well, we can go that way if it's easier. |
|
The tweaking PR: miameows#2 |
Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
|
Well, if we're poking around here, we shouldn't use a table for visual layout. Tables are for tabular data. Let's replace it with a semantic list. This improves accessibility for screen readers, and we can also have a breakpoint to collapse to a single column for mobile. Here's an alternative to @nedbat's PR, also with his wording tweaks: miameows#3 |
picnixz
changed the title
Replace tables with styled lists and add mobile breakpoint
hugovk
left a comment
hugovk
left a comment
There was a problem hiding this comment.
We already expanded the scope of this PR, I agree the sidebar stuff can be a followup.
Thank you!
|
It is often hard to get these things merged. With the finish line in sight, let's not move the finish line further away. |
hugovk
added
awaiting merge
needs backport to 3.13
|
GH-150239 is a backport of this pull request to the 3.13 branch. |
|
GH-150240 is a backport of this pull request to the 3.14 branch. |
|
GH-150241 is a backport of this pull request to the 3.15 branch. |
bedevere-app
Bot
removed
the
needs backport to 3.15
5 participants
Hi folks,
This PR removes a link to "Distributing Python Modules" from the front page of the docs. Said page was empty save for a message telling users to go to packaging.python.org. It was already marked as an orphan, so I removed the link and made a new section for "Other resources", linking packaging.python.org and (at the suggestion of Petr) typing.python.org.
I understand this is a fairly visible change and will probably require some discussion (and possibly modification) before it's ready to merge. I'm here to answer any questions or fix issues.
Before:
After:
cc @encukou (helped me plan this approach) and @nedbat (docs team)
Closes #149902
Thank you!