Make developer documentation more discoverable and organized
Nessuno ha ancora preso questa issue.
Valutazione
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Idoneità per principianti
- 35/100
- Tipo di issue
- Documentazione
- Chiarezza
- Abbastanza chiara
- Stato di attività
- Ferma
- Stack tecnologico
- git, github, markdown
- Ambito
- developer-experience, documentation
Direzione di ricerca
Start by reviewing the existing ReadTheDocs setup and the listed files: test-data/unit/README.md, README.md, CONTRIBUTING.md, and the wiki. Define the developer-documentation section and identify relevant material to move, preserving the existing content. Done means developer docs are navigable on ReadTheDocs and obsolete wiki material is removed.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Descrizione
We have something over 3000 words of developer documentation, spread across several files:
$ git ls-files | grep -e README -e md$ | xargs wc -w | sort -rn
3413 total
1052 test-data/unit/README.md
1015 README.md
1005 CONTRIBUTING.md
181 pinfer/README
139 docs/README.md
21 extensions/README.md
The top-level README has gotten long enough that it's easy to miss things there, which motivated us to split out the discussion of how tests work into a separate tests README. That discussion has grown with a lot of useful content and is also getting long -- and at the same time, because it was split out it's become easy for people to miss that it exists in the first place and that they should read it, as there isn't any significant cross-file navigation available for README files displayed on GitHub.
Zulip has adopted a model of writing developer documentation to display on readthedocs, in the same way as their user documentation. The greater navigation structure available there helps a lot in letting the documentation scale to being readable across a number of files totalling much more information in total -- the model seems to scale pretty well.
Since we already have documentation set up on readthedocs, and our developer documentation is already also in Markdown, I think it should be pretty easy to move our developer documentation there and that will help us out. I'd approach it something like this:
- Make a section in the Mypy docs for Mypy development documentation. Move
test-data/unit/README.mdthere in its entirety, to be the first occupant of that section. - Move all the material in
README.mdwhich is only relevant when developing mypy itself into another file or two in that section. For example "Quick start for contributing to mypy" and "Working with the git version of mypy", and some small pieces of other sections. - Go through the wiki, move everything still relevant to those docs (if developer-facing, or elsewhere if not), and delete the rest.
- Lingua principale
- Python
- Stelle
- 20.6k
- Fork
- 3.3k
- Merge medio
- 1g 18h
- PR unite (30g)
- 54
Guida per i contributori
Apri la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di python/mypy
-
bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 75/100
-
bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
-
bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 76/100
-
documentation
Difficoltà 2/5 1-3 ore Idoneità per principianti 72/100
-
bug topic-configuration topic-error-reporting
Difficoltà 2/5 1-3 ore Idoneità per principianti 68/100
Issue simili
-
bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 86/100
zostera/django-bootstrap4#894 ·
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
use-agent-os/agent-os#3276 ·
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 88/100
zephyrproject-rtos/zephyr#119726 ·
-
area/auth bug comp/agent P3 platform/discord type/security
Difficoltà 2/5 1-3 ore Idoneità per principianti 88/100
NousResearch/hermes-agent#117848 ·
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 82/100
zilliztech/memsearch#759 ·