docs HTML API reference improve usability by splitting into multiple pages
- Dominant language
- Python
- Stars
- 5.8k
- Forks
- 541
- Avg merge
- 3d 2h
- Merged PRs (30d)
- 5
Description
Currently, the class reference is flat. It is a *huge* page and in my opinion this hinders usability. While the Python source splits up Workplane, Assembley, Selector, lower level Geometry, and Topological classes, the HTML docs dump everything into a single large page. The Python source has its structure for a reason and the docs would benefit from a similar structure.
We can search the HTML docs in two ways
- The built-in Sphinx "Search docs" feature
This is very useful but requires extra navigation.
- web browser page search "Ctrl+F"
This type of search can potentially provide quick navigation of the class reference. With the flat page it is difficult to navigate. I think it would make more sense to have say a page for Workplane separate from other classes. Then you would bookmark say the Workplane page when working with Workplane and can quickly navigate the class methods. When working with the say the geom.py classes the user could specifically navigate to a page dedicated to these classes.
As a workaround, yes we can open the source files. Even with the source files open in tabs in a text editor it would be nice to augment this with the HTML reference.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.