Confusing links in generated documentation
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 35/100
- Issue type
- Documentation
- Clarity
- Mostly clear
- Activity status
- Stale
- Tech stack
- python
- Domain
- documentation
Research direction
Start by inspecting the generated API documentation for labthings_fastapi.Thing and submodule symbols such as labthings_fastapi.thing.Thing, then compare references to their displayed destinations. Review how Sphinx autodoc currently generates these entries. Done means deeper definitions consistently link to the intended top-level documentation and the public-versus-internal API split is documented clearly.
Written by the indexing model from the issue text.
Description
Most of the key symbols (e.g. Thing) appear in more than one place in our API, for example labthings_fastapi.Thing and labthings_fastapi.thing.Thing.
Each symbol is properly documented only once, at its intended top-level location (e.g. the proper documentation for Thing is at labthings_fastapi.Thing). However, there are some references to the fully-qualified labthings_fastapi.thing.Thing that end up taking you to that submodule, which has a confusingly skeletal definition of Thing that doesn't link to the main one.
We probably need to manually look through these symbols and ensure that the deeper definitions link properly to the top-level documentation.
In the future, this might be done by not autogenerating the API docs each time, or possibly by having manually structured documentation for the top level labthings_fastapi module and a couple of the user-facing submodules, plus some autogeneration for the rest of the package (which is primarily developer-facing).
I think having a clear split between the API we expect people to use when developing Things and using the library, and the internal API that's mostly for developers, would be very helpful. From what I've read, the preferred way to do this with Sphinx is to have some manual intervention in the API docs. For us, I think the sweet spot is a manually curated set of documentation for the top modules (which absolutely should use autodoc to describe classes and functions - I'm not suggesting it should be entirely manual), plus an autogenerated description of the rest of the API.
- Dominant language
- Python
- Stars
- 9
- Forks
- 4
- PR merge metrics
- No merged PRs in 30d
Contributor guide
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 labthings/labthings-fastapi
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
labthings/labthings-fastapi#405 ·
-
drop-python-version
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
labthings/labthings-fastapi#354 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
labthings/labthings-fastapi#312 · 1 comment ·
-
Difficulty 5/5 Over a week Newbie friendliness 35/100
labthings/labthings-fastapi#404 · 2 comments ·
-
Difficulty 3/5 1-2 days Newbie friendliness 63/100
labthings/labthings-fastapi#403 · 1 comment ·
All issues in labthings/labthings-fastapi
Similar issues
-
bug confirmed issue
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
open-webui/open-webui#30750 · 1 comment ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
OpenwaterHealth/openmotion-bloodflow-app#604 · 1 comment ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
-
good first issue
Difficulty 1/5 Under an hour Newbie friendliness 90/100