PR2: Theory of Operation

[edreamleo]

See #654. Supersedes PR #657. This PR will remain a draft until Phase 3 is complete.

The branch name is misleading—this PR will contain only two .rst files.

• Add theory.rst.
• Add reference to theory.rst in index.rst.
• Phase 1: Write introduction from a newbie's point of view.
  • Write the intro before further study, to avoid the curse of knowledge.
  • Create a list of questions to be answered in Phase 2.
• Phase 2: Study the code in the study branch (not here).
  • There is no need for tracing_utils.py here.
  • See PR: (Permanent draft) EKR's study code #653.
• Phase 3: Complete the first draft.
• Phase 4: Review with @lieryan.

[edreamleo]

@lieryan Rather than create a discussion, I'd like to say here a few words about my approach.

I'm happy to go slowly

I think of this PR as a self-guided graduate course. I'm not sure whether it will take one or two semesters :-)

The absence of documentation (including docstrings) forces me to take at least a brief look at all of Rope's code. I don't mind. The Theory of Operation should say a few words about how type inference fits into Rope's code base.

I'd rather not ask for help just now. Again, this approach forces me to take a close look at all the relevant code.

Ahas should be documented immediately, before the previous confusion/ignorance becomes completely impossible to recreate. No, the Theory of Operation won't be a history of my study, but it should discuss all the questions that newbies will have.

[edreamleo]

@lieryan I am going to close this PR.

I'll use ekr-fork-rope2 to work on the Theory of Operation without bothering you.