[Discussion] Docs rewrite
Chưa có ai nhận issue này.
Đánh giá
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức phù hợp với người mới
- 25/100
- Loại issue
- Tài liệu
- Độ rõ ràng
- Cần làm rõ
- Mức độ hoạt động
- Ít trao đổi
- Công nghệ
- python
- Lĩnh vực
- documentation
Hướng nghiên cứu
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.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Mô tả
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.
- Ngôn ngữ chính
- Python
- Star
- 716
- Fork
- 446
- Merge trung bình
- 8 ngày 8 giờ
- Pull request đã merge (30 ngày)
- 2
Hướng dẫn đóng góp
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của tableau/server-client-python
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 70/100
tableau/server-client-python#1865 ·
-
in-progress
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
tableau/server-client-python#1829 · 1 bình luận ·
-
enhancement gap needs investigation
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 68/100
tableau/server-client-python#1322 · 1 bình luận ·
-
[Type2] Allow Incremental Refresh type schedules to be added via `server.schedules.add_to_schedule` Đang mởhelp wanted Server-Side Enhancement ui-exists
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 68/100
tableau/server-client-python#1101 · 3 bình luận ·
-
enhancement good first issue
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 68/100
tableau/server-client-python#783 · 5 bình luận ·
Tất cả issue của tableau/server-client-python
Issue tương tự
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 75/100
anthropics/skills#1811 · 1 bình luận ·
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 75/100
speaches-ai/speaches#678 ·
-
bug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 75/100
datalayer/mcp-compose#42 ·
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 75/100
conda-forge/spacy-feedstock#177 ·
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 70/100
UKGovernmentBEIS/inspect_evals#2523 ·