General Index vs Domain Index

[Charles]

Hello there!

I could use some help for an extension based on the Recipe tutorial. In my ingredients index, I would like them to be grouped by first letter and display links to each usage of the ingredient, just like the default General Index.

For example, if I used "flour" in four recipes and rendered the index (use ReadTheDocs theme), I would like to get the following result:

(in order to make this mockup screenshot this, I simply used the :index:`flour` role four times in my documents.)

The RecipeIndex provides recipes grouped by their first letter by returning and a list of index entry tuples per first letter:

    content[ingredient].append(

        (dispname, 0, docname, anchor, docname, '', typ)

    )

Here, content is a mapping of first letters to index entries, like sphinx.domain.IndexEntry instances.

In the search for my solution, I looked for how the general index was built and discovered that domain indices and the general index was two completely different beasts.

It seams to me that I'd like to use capabilities of both index implementations but they have pretty much nothing in common. Has anybody did this in the past? An hybrid of the general index and a domain index? And, does anybody knows if there is a longterm intention of merging the two index workflows?

[Charles]

«get the following result» above should be followed by:

[Komiya Takeshi]

Hi Charles,

The recipe tutorial only describes about domain index. To add an entry
for the each recipe to general index, you need to create a node of
addnodes.index on each directives. The general index automatically
collect them and create index page automatically.

For example, PyModule class is a good example for you. Please read the
source code and try it:
https://github.com/sphinx-doc/sphinx/blob/3.x/sphinx/domains/python.py#L994

Thanks,
Takeshi KOMIYA

2020年8月4日(火) 12:25 Charles <cblega...@ntis.ca>:

> --
> You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-dev+...@googlegroups.com.
> To view this discussion on the web, visit https://groups.google.com/d/msgid/sphinx-dev/43221c3d-f013-4665-8e97-d27e4791bb72n%40googlegroups.com.

[Charles]

Thank you very much for this useful information!

I managed to add my entries to the general index, linking the "main" one to the directive definition and others to cross referencing roles.

I do generate a domain index, but still I would have preferred it do look like the general index.  I think I get this feeling because my general index in cluttered with apidoc references (since I only tried the extension from within the extension documentation itself), which would not be the case in the "user" documentation project.

I use this in the context of tabletop role playing game (such as Dungeon&Dragon) world building.  I haven't published anything to pypi just yet, since my codebase is still quite messy.  I intend to add similar features for locations, maybe including html Image Maps for trees of locations, but I guess that attempting to making it work for LaTeX would drive me mad quite quicky.

I am interested in using Sphinx in less technical use cases.

Anyways, thank you for maintaining this project.  I use it everyday both at home and work and I have a lot of fun writing an extension for it!  It is hosted on gitlab.