-
Notifications
You must be signed in to change notification settings - Fork 145
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Reorganize API docs into subpages #927
Conversation
Pull Request Test Coverage Report for Build 5649247472
💛 - Coveralls |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Overall this LGTM, I think this structure will work better once we update the theme package to be the new furo one. Just one inline comment about the max depth for the top level toctree.
I also wonder if we want to mention the new structure in the CONTRIBUTING.md, I thought we said new functions need to update api.rst there, but I can't find it. This is easy enough to do in a follow up PR though, so let's just move forward with this as is and we can look at the contributing documentation in parallel.
=================== | ||
|
||
.. toctree:: | ||
:maxdepth: 1 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think making this depth 2 would be nice so we still retain the list of functions. Especially in the move to furo depth 2 would be needed to show each function in the side bar right? But also for the current pytorch based theme I think having the full function list on the api page is useful, even if a bit overwhelming at times.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
maxdepth
has zero impact on Furo's left sidebar. This is how it renders even with maxdepth set to 1
I think making this depth 2 would be nice so we still retain the list of functions...I think having the full function list on the api page is useful, even if a bit overwhelming at times.
Sounds reasonable to me. We can always change it with one line if we don't like it.
* Reorganize API docs into subfolders * Increase maxdepth for functions page --------- Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com> (cherry picked from commit bca9271) # Conflicts: # docs/source/api.rst
* Reorganize API docs into subfolders * Increase maxdepth for functions page --------- Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
* Reorganize API docs into subfolders * Increase maxdepth for functions page --------- Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
Before, we had one page that listed every single function and class. When combined with the new Furo theme from #926, this resulted in an incredibly big left sidebar because all entries were shown at the same nesting level.
Now, the API docs are organized into subpages. This is what the top-level page looks like:
An example subpage:
The Algorithms subpage (I'm not sure if this should show all functions on the page or not):
This also fixes two issues with the top-level ToC:
<self>
was missinginstall.rst
had an improper heading style, so the 4 headers on the page were being treated as top-level pages in the left sidebar.Now, it looks like this: