Skip to content

Conversation

@StanFromIreland
Copy link
Member

@StanFromIreland StanFromIreland commented Dec 2, 2025

Based on the discussion in the docs community meeting. I propose this, in short, I kept the only remaining content and moved it to an internals.rst file, removing the old "See the InternalDocs" pages.


📚 Documentation preview 📚: https://cpython-devguide--1712.org.readthedocs.build/

# Conflicts:
#	internals/compiler.rst
#	internals/garbage-collector.rst
#	internals/interpreter.rst
#	internals/parser.rst
Copy link
Member

@AA-Turner AA-Turner left a comment

Choose a reason for hiding this comment

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

Unsure if we should churn this if we're going to restructure anyway?

@encukou
Copy link
Member

encukou commented Dec 3, 2025

Isn't this a bit of the restructuring?

@StanFromIreland, do you want to move “Source code layout” to CPython's InternalDocs? Then this part of devguide would only be a list of links. IMO, that would make the purpose and scope a lot clearer :)
The link to InternalDocs link should be first, not last.

@sergey-miryanov
Copy link

Just a note, changes in the InternalDocs should be tied to changes in the DevGuide then. We can remove some sections from the InternalDocs, but DevGuide can still reference to those sections.

@encukou
Copy link
Member

encukou commented Dec 3, 2025

changes in the InternalDocs should be tied to changes in the DevGuide then

Yes. That's the case now, e.g. https://devguide.python.org/developer-workflow/grammar/

IMo we should keep these individual pages with links to InternalDocs, but add a link to the entire InternalDocs directory to each one, for the case that an individual document disappears.
Also, we don't need to list these pages in the table of contents -- they're only there to keep the URL working.

@nedbat
Copy link
Member

nedbat commented Dec 3, 2025

The URLs will still work because they are now redirects in conf.py, no?

@StanFromIreland
Copy link
Member Author

StanFromIreland commented Dec 3, 2025

Isn't this a bit of the restructuring?

That was my thinking too, we'll end up removing these pages at some point, why not do that now? "Baby steps" as some say.

move “Source code layout” to CPython's InternalDocs

Sounds like a good idea, I'll open a PR.

The URLs will still work because they are now redirects in conf.py, no?

Yes, I don't want to leave dead links, so I made them redirect to the single page. We were referencing one of the empty pages in the CPython docs till a month or so ago, so I assume there are quite a few more in the wild.

@StanFromIreland
Copy link
Member Author

I wrote python/cpython#142237 to move it. I will update this PR when it is merged.

@AA-Turner
Copy link
Member

I think it's a shame to move things that are less inherently versioned (e.g. the general source tree layout) to InternalDocs/, as it's no longer on a website (we instead have to use GitHub's markdown rendering). Points taken on the restructuring, so I'll update my -1 to a -0 :).

A

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants