Improve autogenerated SDK documentation
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 30/100
- Issue type
- Documentation
- Clarity
- Mostly clear
- Activity status
- Stale
- Tech stack
- python
- Domain
- documentation
Research direction
Start by inspecting the generated documentation at crossplane.github.io/function-sdk-python/function.html and the Python SDK's protobuf-generated documentation output. Review how the current docs are generated, including whether Sphinx or MkDocs is already used. Done means the documentation has a useful landing page, versioning, and coverage for the protobuf-generated code, with the approach requiring low maintenance.
Written by the indexing model from the issue text.
Description
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
mainbranch. - 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.
- Dominant language
- Python
- Stars
- 12
- Forks
- 15
- Avg merge
- 1d 12h
- Merged PRs (30d)
- 7
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from crossplane/function-sdk-python
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
enhancement
Difficulty 5/5 Over a week Newbie friendliness 42/100
-
enhancement
Difficulty 5/5 Over a week Newbie friendliness 35/100
crossplane/function-sdk-python#199 · 4 comments · 3 reactions ·
-
bug
Difficulty 4/5 3-5 days Newbie friendliness 35/100
crossplane/function-sdk-python#129 · 1 comment ·
-
Dependency Dashboard Open
Difficulty 1/5 Under an hour Newbie friendliness 10/100
All issues in crossplane/function-sdk-python
Similar issues
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
canonical/paas-charm#368 · 1 comment ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
-
tech debt
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
-
Difficulty 1/5 Under an hour Newbie friendliness 90/100
StevenBlack/hosts#3256 ·
-
Difficulty 1/5 Under an hour Newbie friendliness 90/100
qualcomm/qai-appbuilder#275 ·