Add a chapter for introducing common function / class' corresponding source file

[louisom]

Maybe we can add a chapter for common function/class corresponding source file.

For example:

int, long -> `Object/longobject.c <github.com/path/to/file>`_
float -> `Object/floatobject.c` ...
exec -> `foo/bar.c` ..
cProfile -> `Lib/cprofile.py` ...

I'm pretty sure this information is very important for who what to contribute, but not familiar to cpython code base. (For example, where does str stringobject.c goes in 3.7...?)

[ncoghlan]

We currently have the "Directory Structure" subsection in the Getting Started chapter: https://docs.python.org/devguide/setup.html#directory-structure

However, I agree it would make sense to have an expanded "Navigating the code base" chapter (perhaps structure.rst?) that explains things like:

• for Python modules, the typical layout is:
  • Lib/<module>.py
  • Modules/_<module>module.c (if there's also a C accelerator module)
  • Lib/test/test_<module>.py
  • Doc/library/<module>.rst
• for extension-only modules, the typical layout is:
  • Modules/<module>module.c
  • Lib/test/test_<module>.py
  • Doc/library/<module>.rst
• for builtin types, the typical layout is:
  • Objects/<builtin>object.c
  • Lib/test/test_<builtin>.py
  • Doc/library/stdtypes.rst
• for builtin functions, the typical layout is:
  • Python/bltinmodule.c
  • Lib/test/test_<builtin>.py
  • Doc/library/functions.rst

And then explain exceptions like int still being longobject.c, str still being unicodeobject.c, and some of the test files still being named after Python 2 standard library entries even though the standard library modules were renamed in Python 3.

[ncoghlan]

To be clear, I think given this new section, the existing Directory Structure subsection in Getting Started would be replaced by a suitable cross-reference, but not eliminated entirely.

[terryjreedy]

Those 'typical layouts' would have been helpful when I started and even now are a bit helpful. Are the exceptions just not changed yet, or intentionally left for easier backporting to 2.7? In the latter case, will we rename in 2020?

[ncoghlan]

As far as I know it was a combination of:

1. Making it easier to share bug fixes between 2.7 and 3.x
2. As a general rule, it's worth avoiding refactoring your regression tests without a really compelling reason (as that's a good way to inadvertently disable or lose a test and subsequently let regressions slip through)

That said, in 2020+ after the first half of the rationale goes away, "make the code base easier to navigate for new contributors" is likely to count as a sufficiently compelling reason to override the latter concern.