CadQuery / CadQuery/cadquery

docs HTML API reference improve usability by splitting into multiple pages

Open
#834 3 comments 2 reactions 0 assignees View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.