2

I am using sphinx-autodoc for documenting a class. I want the methods of the class to correspond to individual entries in the Sphinx TOC, so that they each spawn a link in the 'local TOC' sidebar.

How can I achieve this?

AFAICT, the autoclass directive does not support this. I tried to use autosummary, but I can't get that one to work either: it wants the individual methods in separate .rst files. I would rather have them all on the same page.

I guess I could manually create a section for each member like so:

Foo.bar()
---------

.. automethod:: Foo.bar

But that feels weird and unnecessarily complicated.

polwel
  • 597
  • 5
  • 17
  • Are we talking about the Sphinx [`.. toctree::`](https://www.sphinx-doc.org/en/1.5/markup/toctree.html) directive or the reST [`.. contents::`](https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents) directive?? The code you are showing doesn't have the directive so there's no way to distinguish between the 2 and both are sometimes called *"Table of contents"*. – bad_coder Jan 20 '21 at 13:22
  • Neither. I want the internal document hierarchy to include a separate node for each function. The 2 ways to do this that I know of are 1. include another file via `.. toctree::` or extra sections inside a single reST source file. I am however looking for a way that works with a single file, yet does not require me to manually create sections. – polwel Jan 20 '21 at 13:28
  • So the main requirement is only the "sidebar TOC" having 1 link per method once you get to a given page of the documentation? Do you want that methods only on that specific page? Do you want methods one level under classes? Do you want several classes in the same page? What should a given page have in relation to the "sidebar TOC"? – bad_coder Jan 20 '21 at 13:37
  • Yes, exactly, the sidebar should list the methods, and link to them. I do not particularly care about the hierarchy of class vs methods, since I intend to have one page per class. Not sure if I understand your last question. The sidebar contains the local TOC, i.e. the contents (sections, subsections, ...) of the current page (as opposed to the contents of the entire documentation). Thx for your help. – polwel Jan 20 '21 at 14:45
  • OK, that needed to be clarified because otherwise a contributor could post an answer that turned out to not be exactly what you want. I haven't used `autosummary` yet myself but you are right, to avoid writing one section above each method it's probably the best choice. (I'm currently busy and can't take the question today, but I wanted to contribute towards a clarification in the meanwhile.) – bad_coder Jan 20 '21 at 14:53

1 Answers1

2

I wrote a sphinx plugin called autoclasstoc that does something similar to what you want. The plugin provides a directive that creates a table of links to the documentation for each method of a particular class. The links don't end up in the TOC sidebar, but they still make the class documentation much easier to navigate. It's also worth mentioning that these links can be organized into groups (e.g. public methods, private methods, etc.) and that links to inherited methods are grouped by superclass and collapsed by default.

Even though this doesn't exactly answer your question, it's a good way to achive a similar effect.

Kale Kundert
  • 1,144
  • 6
  • 18
  • Neat, that is definitely an improvement! You seem to be familiar with the inner workings of docutils. Is there an easy way to expand `autoclasstoc` to also emit the document TOC entries? – polwel Jan 21 '21 at 08:36
  • That's a good question. I don't know off-hand, because I don't know exactly how things end up in the TOC, but it could be pretty straight-forward. If you want to open an issue in the bug tracker about this, that would be a good place to continue this conversation. – Kale Kundert Jan 21 '21 at 17:28