Skip to content

Document Structure and Wishlist #845

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
1 of 10 tasks
srittau opened this issue Aug 23, 2021 · 1 comment
Open
1 of 10 tasks

Document Structure and Wishlist #845

srittau opened this issue Aug 23, 2021 · 1 comment
Labels
topic: documentation Documentation-related issues and PRs

Comments

@srittau
Copy link
Collaborator

srittau commented Aug 23, 2021 •
edited
Loading

Here is how I envision the typing documentation to be structured:

Tutorials

User-facing basic and advanced introductions to the type system or particular aspects of it. Non-comprehensive.

  • Typing tutorial – from the ground up (Tutorial document #891)
  • Type stub tutorial – writing a type stub for an existing library, stubgen, contributing to typeshed

Howto Guides

Directory: /guides

User-facing guides to accomplish particular tasks.

Reference

Directory: /reference

User-facing, comprehensive reference of the type system.

  • Link to the typing module documentation
    • Probably needs a review
  • Best Practices document #851
  • Type stub syntax and supported constructs
  • Type stub style guide

Type System Specification

Directory: /spec

Territory of the Typing Council. Targeted at type checker developers. Here be dragons. 🐉

Links

Top level.

  • Links to all typing-related PEPs
  • Links to type checkers and other typing tools

Additions, corrections, criticism welcome!

2014-09-02: Updated to reflect the addition of the type system spec. Also, added explanations to the categories.
@srittau srittau added the topic: documentation Documentation-related issues and PRs label Aug 23, 2021
@srittau srittau mentioned this issue Aug 30, 2021
Closed
@srittau srittau mentioned this issue Sep 13, 2021
Open
@srittau srittau mentioned this issue Nov 9, 2021
Closed
@sobolevn
Copy link
Member

Might be helpful, quick eco-system overview: https://github.com/typeddjango/awesome-python-typing/

srittau added a commit to srittau/typing that referenced this issue Dec 22, 2021
@srittau
Improve TOC structure
69eb6b9 
* Add section headers to the toc tree
* Add a "Guides" section and put the libraries document there
* Move the link to the typing documentation into the "Reference" section

Cf. python#845
@srittau srittau mentioned this issue Dec 22, 2021
Merged
JelleZijlstra pushed a commit that referenced this issue Dec 22, 2021
@srittau
Improve TOC structure (#988)
ae26334 
* Add section headers to the toc tree
* Add a "Guides" section and put the libraries document there
* Move the link to the typing documentation into the "Reference" section

Cf. #845
@AlexWaygood AlexWaygood mentioned this issue Apr 14, 2022
Open
@adam-grant-hendry adam-grant-hendry mentioned this issue Sep 18, 2022
Closed
srittau added a commit to srittau/typing that referenced this issue Jul 15, 2024
@srittau
Remove empty documents
607c2e7 
These documents were part of a proposed structure. In the meantime, the
structure has diverged from the proposal. We also have issue python#845 to
discuss a structure if we find time in the future to work on this.
@srittau srittau mentioned this issue Jul 15, 2024
Merged
srittau added a commit that referenced this issue Jul 15, 2024
@srittau
Remove empty documents (#1801)
d899429 
These documents were part of a proposed structure. In the meantime, the
structure has diverged from the proposal. We also have issue #845 to
discuss a structure if we find time in the future to work on this.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
topic: documentation Documentation-related issues and PRs
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@srittau @sobolevn