Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

[Discussion] Docs rewrite

Aperta
#1,451 8 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
25/100
Tipo di issue
Documentazione
Chiarezza
Da chiarire
Stato di attività
Tranquilla
Stack tecnologico
python
Ambito
documentation

Direzione di ricerca

Review the documentation on the gh-pages branch, the existing Markdown files, and the relevant .py files containing type hints and docstrings. Read the proposed Sphinx autodoc approach and assess how the documentation could be represented in reStructuredText while preserving publication to gh-pages. The issue does not define a specific migration scope or completion criteria.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

docs

Currently, documentation is maintained on a separate branch, gh-pages, and written in Markdown. With all of the type hints that have been incorporated over the last few releases, IDE/LSP's will have better information about what function signatures are available and being used. Python's default way of making documentation available to users is through docstrings.

What I propose is that instead of separately maintaining the documentation, especially the user facing TSC API documentation, separately, that it be maintained through docstrings in the .py files. Then the markdown that is currently being used is converted to reStructuredText. This would open up the ability to use sphinx and its autodoc extension to read those docstrings and produce the web navigable documentation. I believe the docs could still be published to gh-pages, so URLs would not have to change.

.rst is definitely not as simple of a format as .md, but the ability to fetch docstrings and function signatures I think offers a clear advantage over continuing with markdown.

Lingua principale
Python
Stelle
716
Fork
446
Merge medio
8g 8h
PR unite (30g)
2

Guida per i contributori

Apri la guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di tableau/server-client-python

Tutte le issue di tableau/server-client-python

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.