gh-119786: move 'exploring' doc from devguide to InternalDocs

[iritkatriel]

---

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

[nedbat]

I think it might make sense to leave this in the devguide. It is overview and will not change frequently. People might need this kind of help to find their way into the cpython repo.

[iritkatriel]

I think it might make sense to leave this in the devguide. It is overview and will not change frequently. People might need this kind of help to find their way into the cpython repo.

I'm happy to leave the directory structure overview.

The second part (links to external resources) does seem to fit with the internals docs, though. Do you agree?

[willingc]

Here's what I think makes sense. I think this should remain in the developer/contributor guide for now. I think it is also fine to copy the contents to the Internals Doc in the CPython repo.

The source code layout is helpful for people navigating contribution.

Most of the resources are general and written by external individuals. We may want to curate this list.

So that, then begs the question of duplication of information which is not necessarily bad. I could see the docs diverging over time. CPython repo containing low level implementation details and contribution guide providing a pathway to understanding the internals. In the contribution guide, we can provide the content and guide the reader to the internals documentation which should be the source of truth after the source code on internals.

[willingc]

Just curious since I wasn't able to attend the sprint to ask you in person @iritkatriel, what is the vision and primary purpose for the internal docs? I want to make sure that I have a sense of what the expectation of the Internals Docs relative to the other documentation in the project ☀️

[iritkatriel]

Just curious since I wasn't able to attend the sprint to ask you in person @iritkatriel, what is the vision and primary purpose for the internal docs? I want to make sure that I have a sense of what the expectation of the Internals Docs relative to the other documentation in the project ☀️

The problems I'm trying to solve are

1. documentation on internals was scattered in several places so not easy to discover.
2. it was not in the same repo as the code, which made it less likely to be kept up to date (now you update it in the same PR as the code change)
3. It wasn't versioned in the devguide, so once it's updated to the current dev version we lose information about previous versions which are still supported (or, we need to have the same doc discuss different versions, which can be confusing). In the future, the docs for older versions will remain in the repo in that tag.
4. Quality is inconsistent as some of the internal doc are not very polished. They are also incomplete, but we don't have a view of what's missing.

[willingc]

Thanks @iritkatriel. That's super helpful re: scattered docs which I agree with. I'm curious about thinking about the CPython docs, Internals Docs, and dev/contributor guide, and having a clearer strategy moving forward.

For now my recommendation, would be to move to the InternalsDocs and also leave here.

[willingc]

Let's close this PR but go ahead with merging the CPython PR. Leaving the Devguide contents unchanged for now.