Skip to content
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

Allow which toctree node the entries are placed under to be configurable #97

Closed
AWhetter opened this issue Feb 8, 2017 · 2 comments
Closed

Comments

@AWhetter
Copy link
Collaborator

AWhetter commented Feb 8, 2017

It would be nice to be able to configure which toctree node autoapi adds itself to. Currently this is hardcoded to "index" (https://github.com/rtfd/sphinx-autoapi/blob/5529237fb5012039d248abccdf61865aace5fb32/autoapi/extension.py#L117).
For example I have the case where my documentation is split into a user and technical section. I want the API docs to reside under the technical section rather than at the top level.

The README says

AutoAPI will automatically add itself to the last TOCTree in your top-level index.rst.
...
We hope to be able to dynamically add items into the TOCTree, and remove this step. However, it is currently required.

I don't really know what this means but it sounds like it would mean implementing a similar thing?

@AWhetter AWhetter changed the title Allow the toctree node the entries are placed under to be configurable Allow which node the toctree node entries are placed under to be configurable Jun 12, 2017
@AWhetter AWhetter changed the title Allow which node the toctree node entries are placed under to be configurable Allow which toctree node the entries are placed under to be configurable Jun 12, 2017
@AWhetter
Copy link
Collaborator Author

AWhetter commented Sep 1, 2017

Closing because I think it makes more sense for a user to set autoapi_add_toctree_entry to False and then add a toctree entry for /autoapi/index.rst wherever they want autoapi included.

We ever go as far as to put /autoapi/<my_package>/index.rst in our toctree so that we don't get the top level autoapi index file.

@AWhetter AWhetter closed this as completed Sep 1, 2017
@sammorley-short
Copy link

sammorley-short commented Aug 16, 2023

@AWhetter I tried your suggested solution and it didn't work (autoapi_add_toctree_entry = False and then adding /autoapi/index.rst to the specific toctree directive where I wanted to add it.

To be more specific, with autoapi_add_toctree_entry = False, then I get the error WARNING: toctree contains reference to nonexisting document 'autoapi/index'

One workaround is to then set autoapi_root and then reference path/project/index in a TOC, but this then means the sidebar entry is just the package name, rather than API reference, which is preferred.

Did something change or is this still supported?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants