Initial full TOC structure for typing docs content #919
Conversation
| @@ -0,0 +1,3 @@ | |||
| ********** | |||
| The Basics | |||
There was a problem hiding this comment.
mypy's cheat sheet (https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html) is the most visited page in mypy's documentation, I'm assuming this will be something similar?
| ---------------- | ||
|
|
||
|
|
||
| Runtime Considerations |
There was a problem hiding this comment.
If it's useful, I recently rewrote mypy's documentation for this: https://mypy.readthedocs.io/en/latest/runtime_troubles.html
| ------------------ | ||
|
|
||
| Advanced Types | ||
| -------------- |
There was a problem hiding this comment.
I'm guessing Literal goes in here?
| ----------- | ||
|
|
||
|
|
||
| Protocols and Duck Typing |
There was a problem hiding this comment.
I assume this is where we cover int <: float <: complex and the other special cases?
| Classes | ||
| ======= | ||
|
|
||
| Overloads and Overrides |
There was a problem hiding this comment.
Overloads feels more functions-y, is overrides meant to talk about Liskov Substitution Principle? Potentially worth separating
| The Class Hierarchy | ||
| =================== | ||
|
|
||
| Mutable Containers |
There was a problem hiding this comment.
It might make sense to move the section to where we introduce generics, since it's hard to have any discussion of variance without examples.
| ============= | ||
|
|
||
|
|
||
| Type Variables |
There was a problem hiding this comment.
Maybe type variables should be introduced before generic types?
|
I've been waiting until this lands to work on python/mypy#11506 , but it looks like it's maybe stalled. |
|
@sirosen Thanks for pinging on this PR again! Would love to unblock documentation work and any changes on top of this initial structure - if no objections, can we merge it? cc @JelleZijlstra (not sure what the best way is to flag to someone with write access) |
|
Thanks Jelle! :) I'll plan on putting up another iteration of TOC with some more details and a few of @hauntsaninja's suggestions from above. Will wait on @sirosen to stack anything first. |
|
It seems that the links to the two existing documents and the reference documentation have vanished. Could we please restore them? |
|
Also, I'm not too happy that we have only empty documents now. I suggest to comment out all links to non-existing documentation for now. Empty documents are worse than non-existing documentation, as they lower the confidence of users coming across this page that there is useful content behind the links. |
|
I'll look at doing a cleanup PR now, ahead of doing any further work. I'm just "claiming" this to hopefully save others the duplicate work.
I'm going to remove these from toctree directives, but leave the old docs in place. Sphinx will warn about the pages being built but not included in any toctrees, but I think that's best. Where appropriate, I can comment out whole toctrees. I'll try to figure out something which works.
I only see the link to https://docs.python.org/3/library/typing.html having been removed. Was there another one I'm missing in the diff? |
Happy to see initial content landing for type system documentation. In order to avoid repeat topics or a tangled refactoring job later on, I'm looking to propose an initial TOC structure for topics we think are valuable to cover. Hopefully this can serve as a starting point to branch off of, and to fill in as we go.
The existing two pages have content that we may want to split up in the future, i.e., the current "libraries" page tackles general topics like type aliases, decorators, etc. I've left that content untouched and just linked to those pages for now, to avoid tackling too much in this PR discussion.
RFC on the details of the contents and structure here. I'm hoping we can settle on something that is both clear and easy to skim for a developer who is just starting to familiarize with the basics, but that also provides organized in-depth guidance for developers who work with types but need to iron out a complex typing issue or understand an advanced topic. Is anything missing?
For easier visualization of initial TOC structure proposed here:
