Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

[Discussion] Docs rewrite

Aberta
#1,451 8 comentários 0 reações 0 responsáveis Ver no GitHub

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
5/5
Tempo estimado
Mais de uma semana
Facilidade para iniciantes
25/100
Tipo de issue
Documentação
Clareza
Precisa de esclarecimento
Status de atividade
Pouca atividade
Stack de tecnologia
python
Domínio
documentation

Direção de pesquisa

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.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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.

Linguagem predominante
Python
Estrelas
716
Forks
446
Merge médio
8d 8h
PRs com merge (30d)
2

Guia de contribuição

Abrir o guia de contribuição

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de tableau/server-client-python

Todas as issues de tableau/server-client-python

Issues semelhantes

Mais issues de Python

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.