crossplane / crossplane/function-sdk-python

Improve autogenerated SDK documentation

已關閉
#36 2 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視
documentation enhancement
主要語言
Python
星號
12
分支
15
平均合併
1 天 23 小時
30 天內合併 PR
6

描述

### What problem are you facing?

We have autogenerated SDK documentation at https://crossplane.github.io/function-sdk-python/function.html, but it's not great.

Some things that could be improved:

* There's no versioning - the generated docs always and only reflect the `main` branch.
* The landing page is empty.
* There's no documentation for the protobuf generated code.

Documentation for the protobuf generated code seems like it would be very valuable, since there's not much else to this SDK apart from a few utilities. Unfortunately the code itself doesn't seem to have docstrings, despite the protobuf messages it's generated from having them.

### How could this Function help solve your problem?

* Figure out if there's some way to copy docstrings from the protobuf schema to the generated code.
* Use a better docs tool (Sphinx, mkdocs, etc). Ideally something low maintenance.

貢獻指南

這個儲存庫沒有索引到貢獻指南

研究方向

首先檢查 crossplane.github.io/function-sdk-python/function.html 中產生的文件,以及 Python SDK 的 protobuf 產生文件輸出。檢視目前文件的產生方式,包括是否已經使用 Sphinx 或 MkDocs。完成的標準是:文件具有實用的登陸頁面、版本管理,並涵蓋 protobuf 產生的程式碼,同時所採用的方法需要較少的維護工作。

由索引模型根據 Issue 內容生成。

評估

技術堆疊
python
領域
documentation
Issue 類型
文件
難度
5/5
預估耗時
一週以上
活躍度
停滯
描述清晰度
基本清楚
新手友好度
30/100

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。