Sphinx: Implement a py-classindex and py-funindex additionally to the default py-modindex

[Naereen]

Hi, sphinx lovers and coders.

Suggestion: py-classindex and py-funindex as well as py-modindex

Does anyone else think it could be useful to have, let say, two new pages (for the python domain), that could be called py-classindex and py-funindex, in the same way as the default py-modindex page that lists all the modules:

• py-classindex to list all the classes in all the documented modules,
• and py-funindex to list all the functions in all the documented modules.
• (and we can imagine the same thing for constants, any other idea ?)

For an idea of how this would look, have a look to this example documentation (the author does this dynamically).

How ?

It should not be too hard to do from the static point of view:

• one template page (very close to the one for py-modindex)
• and some piece of code in the Python domain module.

If someone could please help by pointing out where to write these, I will try to do it myself :smile:!

Wait...

That's not a new question?

→ No, but it should be answered more cleanly

It should be easy to implement it statically, and is the clean way to do it, instead of some dynamic tricks.
By this StackOverflow question, I can see I am not the only one interested in this feature, and for instance its only answer offers a "simple" trick based on jQuery (cf. this script).
Nothing dynamic and complicated should be needed, the solution should be from the sphinx side.

Other domains?

Of course, if it is not too hard and if it works for the Python domain, we can try to add the same thing for others domains (at least C/C++).

[Naereen]

@viblo: you might be interested by this?

[viblo]

@Naereen Yes, I think its a great idea. I would definitely prefer it over the dynamic jquery stuff pymunk uses now.

You wrote

py-classindex to list all the classes in all the documented modules,`

If you mean all classes in all the modules I think it can get very messy. If you still want it may I suggest and option to either do it for all, or otherwise just for the current module?
As you can see in the pymunk docs I only display the classes in the current module (and not whats in submodules / sibling modules).

[Naereen]

@viblo Indeed it can get messy if there is too many classes, but by default the genindex page does this: list of all modules, classes, constants and functions (and it can be messy, e.g. if many similar functions are defined in different modules).

It could also be some new directives, maybe .. py-listclass::, .. py-listfun:: and .. py-listvar:: that can be put in any page, and if this page documents a module, it gives only the list of classes/functions/variables in this module, otherwise the complete list.

[quentinbodinier]

Kudos to @Naereen for starting the discussion. (and @viblo for the jquery based solution which is a great fix).

The main problem I see is that sphinx is module-oriented which makes sense for scripting programs but is far less adapted to object-oriented projects, where it makes much more sense to organize the API according to classes and not modules. Note that I may think so because I come from a JAVA background as well.

I agree with you that it may get a bit messy but I think the main idea is to give the possibility to access classes directly instead of modules. For example see the java api : https://docs.oracle.com/javase/7/docs/api/
In there you can list all classes, or list classes of a specific package. It makes more sense like this because people tend to look for the documentation of a specific class, without necessary prior knowledge of the module it is from. This must definitely be doable without not too much hassle in sphinx as well.

[tk0miya]

+1 for py-classindex and so on.
But I prefer python to implement it. Because javascript could not support LaTeX and other formats.

[viblo]

@quentinbodinier Im not against the option of listing all classes, I only want to point out that I think the "see only classes of a single module" is important, and Im not sure I would use this feature unless its possible.

@tk0miya Agree with you. I wrote my version as a dynamic javascript only because it was easy to do and I didnt have the time to figure out how to implement it "properly" at that time. I definitely think a non-dynamic version in python is better.

[Naereen]

Any update?

[tk0miya]

Nothing changed yet.
Now we released Sphinx-1.5 last week. And we'd received some bug reports for the package.
So now we are working for the bug fixes. there are no time for improvements.

Anyway, we have tons of issues and proposals. So I can't promise you when this will be finished.
Of course, all pull requests are always welcome :-)

[Naereen]

I understand.

As I said, I will try to do it myself, but I don't know which file I can work from.
Could you please indicate me how (and where) the py-modindex is generated in the Python domain ?

[tk0miya]

Sorry, I don't know in detail.
But, Only what I know is py-modindex is generated by sphinx.domains.python.PythonModuleIndex.

[Naereen]

OK; thanks. I will try to work from there.

[Naereen]

I tried, please let me know if it does the job or if it insufficient. (it looks enough to me)

[Naereen]

Here is a demo of how it looks on a "real" project:

• fun index: example 1, example 2,
• example 3 with many functions with the same name implemented by different modules,
• class index: example 4.

[Naereen]

@quentinbodinier @viblo do you think this feature is enough?

If not, do you have any suggestion/wishes of how to do it differently / better ? Thanks.

[viblo]

@Naereen Now I had the chance to try it out briefly.

I have a bunch of comments:

1. Since modindex and funcindex uses short version, should the other index also be called their short versions? Like methindex and so on (Names from here http://www.sphinx-doc.org/en/1.5.1/domains.html#cross-referencing-python-objects ?)

2. I still like the way I have a short partial index on each submodule page in pymunk doc, so unless its possible to do that I will continue with the jquery hack :)

3. In general I like it and would probably add the different index to pymunk docs regardless of point 2, since they give a nice overview.

4. All index are expanded by default. But, if I add a common prefix it seems random. Methodindex is expanded, but Classindex is not. Would be good if they always defaulted to expanded (or at minimum was consistent)

5. You have inconsistent tabbing in std.py, you will see it easily in the side by side view here on github.

Btw, it seems like your examples are offline now.

[Naereen]

@viblo Sorry about the examples, I forgot to update the link from funindex to funcindex.
Thanks for the others remarks.

1. I updated this (cf. 013f6b7),
2. As said, this feature would require a new directive, I don't feel very comfortable into trying this right now. Any suggestion on the good name this/these directive(s) should have ?
3. Glad to know that :-)
4. I don't understand, what do you mean by expanded ?
5. The tabbing inconsistency was intentional, to separate the genindex and search links from the others.

As @shimizukawa said, I shouldn't even modify sphinx/domains/std.py for this Python domain specific feature, but when I try to add these labels & anonlabels values in sphinx/domains/python.py it does not work in pure .rst files (cf this example).

[viblo]

@Naereen

1. Here is the class index, where the tree nodes are not expanded by default (I also have a very ugly expand button, but I suspect its my css and not your change that creates that
   
   Then here is the method index, where the tree nodes are expanded:
   

[Naereen]

Oh OK. This is not something I programmed, I think it's a matter of DOM cache. Try the same page on an other browser ?

Here is an example, by default the py-classindex.html as exactly the same behavior than the others (for me, on Firefox):

By the way, I found a surprising feature, on the basic theme, all the new index pages are added to the relbar2 block (links to next, prev, index etc on top right and bottom right horizontal bars). You have that in your examples as well. It's very neat.

[viblo]

@Naereen

1. I assume they would go into the python domain? I guess 3 options exists:
   
   
   
   1. Use one directive for all index and name it index, and then let it take an argument to define what index should be shown. But maybe this is not the best way, since the index pages are separated and it would give less easy control.
   
   
   2. Reuse the name, so it becomes .. py:modindex::, .. py:funcindex:: and so on. Good with this option is its the same as the page name so easy to remember and consistent. Bad is that .. py:mod:: means a reference to a module, not the actual module, so maybe you would think modindex means reference to the module index (same as :ref:`modindex`)
   
   
   3. Make a long name .. py:moduleindex::, .. py:functionindex:: and so on. Good that its not colliding with the references. Bad that its not consistent with what the page is called.
   
   

I think I would prefer option 2.

[viblo]

@Naereen I tried in both chrome and firefox, and I get the same result with class index not expanded but method index not expanded.

[viblo]

@Naereen Regarding the relbar2, its also there in the classic theme (which is what I use for pymunk). Maybe it get a bit crowded to have all of them there?

[Naereen]

For this directive, yes it would go in domains/python.py. I think I have an idea how to do it, will try that tomorrow.
I agree that option 2 seems to be the best.

So the new features would be both:

• the index pages, one page per type of objects, for the whole project (one global page py-classindex.html etc)
• and the directives, .. py:TYPEindex:: etc, to be used on a specific module documentation page, to include the local list of objects of type TYPE from this module.

Is this what you meant?

And for the expanded / not expanded issue, it comes from the "heuristic" used to compute the boolean collapse, same code from class and method index but different env so not detected similarly.

[Naereen]

The classic theme imports files from basic/ folder, sorry. Indeed, the name of the default (old style) theme is classic.

I mentioned here that having all these links in the relbar2 could be annoying.

[viblo]

@Naereen
For the feature: Yep, that is what I mean. But of course you can always do the non-directive first in case its a lot of work.

For expanded/not expanded: Ok. Then it is good I guess :)

[Naereen]

OK. I will try quickly the directive thing.

[tk0miya]

Now I close this because the proposal was rejected at #3278.
Thank you for proposal.

[Naereen]

It's alright.

I didn't have the time to implement this feature as a sphinx extension, sadly.