sphinx
sphinx copied to clipboard
sphinx-doc
Allow creating a cross-reference target for entries in the index
Is your feature request related to a problem? Please describe. I am grouping together a number of topics under a common topic in the index, mostly server names grouped by the type of server they are. Or using wording from https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#index-generating-markup multiple "context" under one "execution".
In the rest of my document I'd like to be able to refer to the list of common topics in the index, by using a cross reference to the entry in the index. I tried using ".. index:: <...> :name: label", but that sets label as an anchor for the following heading in the text, not as an anchor in the index (which is what I had expected).
Looking in the generated index, there are no anchors defined for index entries, and I can't see anything in the above documentation for ".. index::" that mentions this concept.
Describe the solution you'd like I'd like an option for ".. index::" that hows defining a cross reference target for the generated index entry (for simplicity to users, this should be allow to be repeated as long as it is for the same index entry).
Describe alternatives you've considered Having a manually maintained list of server names, but as the files about each server is being generated by multiple different runs of a tool, this seems sub-optimal.
I can also see this being a useful method to refer to groupings of pages in the index.
@puck so if we have two sets of servers - storage and compute, for example, and each set contains a number of themed names, such as:
storage hosts: [diskly-001, diskly-002, tapely-001, flashly-001]
compute hosts: [cpu-001, cpu-002, cpu-003, gpu-001, gpu-002]
...and assuming that those are described within RST page(s) in the documentation, then what is the intended format for the generated index that you're looking for?
Should it be:
S
site configuration
storage hosts
diskly-001
diskly-002
flashly-001
tapely-001
system requirements
... or simply:
S
site configuration
storage hosts
system requirements
...or some other layout?
The reason I ask: it seems like it might be possible to use the inline :index: variant of the (block-level) .. index directive - but I'm not completely sure whether that helps for your use case.
Describe alternatives you've considered
I don't know about the alternative that jayadission proposed, but to keep things simple I use a glossary for the kind of use case you are describing.
To have an index you generally need domain declarations and you aren't showing any example.
Please notice that Sphinx's GitHub issues are dedicated to reporting bugs and posting feature requests. If you have a usage question and need help such questions should be asked at Stack Overflow.
jayaddison, I was thinking the former, I have individual pages for each host (and for services to gather information about network ports and database names). For the server example I have something like this at the top of each page (imagine a file per host):
Example file: cluster1/hosts/diskly-001.rst:
.. index:: storage hosts; diskly-001
diskly-001
========
... auto generated information about this host
Then in the index I'd expect to see the first example you give:
S
site configuration
storage hosts
diskly-001
diskly-002
flashly-001
tapely-001
system requirements
I've just experimented with the ":index: ..." version, and I don't see that it makes it any different, also I can't get ii to use ":name:" in any case.
electric-coder, I'm not aware of anything else that does this gathering of information from multiple pages about one topic into one place, and an index seems like the natural place to look for it. The concept of inserting an anchor already exists for an index, just the ability to add an anchor to "storage hosts" above is missing.
I didn't think a glossary would work, and it doesn't, if I do something like this:
Example file: cluster1/hosts/diskly-001.rst:
.. glossary::
storage hosts
:ref:`diskly-001`
.. _diskly-001:
diskly-001
========
... auto generated information about this host
Example file: cluster1/hosts/diskly-002.rst:
.. glossary::
storage hosts
:ref:`diskly-002`
.. _diskly-002:
diskly-002
========
... auto generated information about this host
Then when I compile the docs, it fails with "duplicate term description of storage hosts". Which is understandable.
I'd note that this concept would also be really useful for "see" and "seealso" index entries, where those could become links to the entry they're referring to. I was bit surprised that this didn't happen automatically when I used them.
Thinking a little further, perhaps all index entries should have an anchor like index; <index entry> where index; is a fixed string to make it less likely to clash with other cross reference targets as <index entry> (the actual index entry) is quite likely to already exist.
jayaddison, I was thinking the former, I have individual pages for each host (and for services to gather information about network ports and database names). For the server example I have something like this at the top of each page (imagine a file per host):
Example file: cluster1/hosts/diskly-001.rst: .. index:: storage hosts; diskly-001 diskly-001 ======== ... auto generated information about this hostThen in the index I'd expect to see the first example you give:
S site configuration storage hosts diskly-001 diskly-002 flashly-001 tapely-001 system requirements
That seems fairly close. What about if you specify the single entry type, and also the name option?
Like so:
.. index:: single: servers; server001
:name: server001
Describing a server named server001.
Reference to :ref:`another server <server002>`.
.. index:: single: servers; server002
:name: server002
Describing a server named server002.
When I attempt that, I get a group of servers in the generated index page -- sub-items server001 and server002 appear in there -- and each one can link to the description of the other.
I think that was similar to something you mentioned earlier, although you said that linking to the headers was a problem. Is that still true if you can move the .. index directive?
And yep, it does seem that the inline version, :index: doesn't support creating a label name; my mistake.
Yes, using :name: server001 etc does work, and puts an anchor into each page, as I noted when I first created this ticket.
The feature I'm suggesting is to have an anchor put into the generated index so that we can link to that. So, in HTML the index page would have something like this (I'm going to simplify the HTML from what Sphinx generates to make what I'm suggesting more obvious):
...
<li><a href="server-types.html#storage-hosts" id="storage hosts">storage hosts</a>
<ul>
<li><a href="servers/diskly-001.html#index-0">diskly-001</a></li>
<li><a href="servers/diskly-002.html#index-0">diskly-002</a></li>
...
See the "id=" on the index entry for "storage hosts"? Having an anchor like that would allow us to say see in the index all servers of type :ref:"storage hosts" (I can't put backticks in the :ref: due to gitlab limitations). It would also allow the "see also" index entries to link directly to the other index entry instead of being plain text and requiring people to scroll around (or for PDFs etc page back and forth.
@puck Ok; yep, got it - I wanted to make sure I had the correct understanding. To confirm:
Currently it's not possible to link to an individual entry on the genindex.html page, because the entries there do not have anchors.
(each letter has an anchor - so it's currently possible to link to Sphinx index entries beginning with A, for example - but not to individual items)
You're not asking for every entry to have an anchor -- but your expectation was that the .. index directive's name option should create an anchor in the index.
(although I think it might be OK simply to create anchors for every entry in genindex.html, that might have unexpected side-effects and so perhaps it's easier to start by allowing individual anchors)
If that understanding is correct, I'd suggest retitling this to something like:
Feature request: add HTML anchors for named genindex entries created by the 'index' directive
Hey,
Yes, your interpretation in https://github.com/sphinx-doc/sphinx/issues/11918#issuecomment-1917067457 is correct. Given the behaviour of .. index directive's :name: option, that couldn't be re-used, something like :indexname:, this is used then it'd need to be allowed to be repeated, as long as it points to the same index entry, and goes with the index entry, not a sub-entry.
I don't think this should be limited to only the HTML generator, as I could see it being useful for LaTeX etc.
I think that it could be useful to have more anchors in the index, as it'd allow the "see also" and "see" entries to have links to what they're referring to - this may negate the need for a new option on the .. index directive.
Cheers, Andrew
To clarify: I was solely talking about enabling an HTML anchor (id attribute) on the genindex.html page, to address your use case. I'm not familiar enough with the index build process to determine whether 'true' cross-references to the index are feasible and/or a good idea.
All good, just wanted to point out in that specifying "HTML" in the issue title might limit what people think I'm talking about here.
Ah, OK. I don't think it'd be straightforward to achieve this in a multi-format manner - there are various programs that can be used to generate an index (see mendex, makeindex, xindy as a few options for LaTeX), and to my knowledge they don't all produce standard format linkable index entries - I could be mistaken about that, though. That would make it difficult for Sphinx to know what type of link to emit at build-time (even though it knows the intended file format).
The core of the problem, I think, is that generally index entries are not part of the source project material. Or to put it another way: indexes are constructed from a documentation project, but may vary in style and content, making it difficult to guarantee that any given entry will be linkable (or exist at all).
As an exception, in the case of the HTML builder and an explicit .. index entry with a fixed name, I think it'd be OK to emit an anchor for the corresponding index element -- but again we can only do that easily in output formats where Sphinx itself generates the index (HTML).
Please note: I could be mistaken about much of the above, and would welcome corrections; I'm very much still learning the internals of Sphinx, and volunteering time where I can.
Are there any other similar documentation projects we could look at to compare and validate the approach?
Ah, yeah, that all complicates matters! HTML would certainly be a very useful starting place.
Sorry, Sphinx is the only documentation system (other than wikis and hand crafted HTML) that I've used, so I don't know of other examples.
@puck after beginning a prototype of this locally, I've realized that even for HTML indexes, the format of the generated index entries (in genindex.html, and/or the split variant) is specific to each Sphinx theme.
I'd like to ask what theme you are using currently, and whether you would find it acceptable to make some local edits to that theme to achieve what you're after (generally this isn't a great idea, but it may allow you to achieve what you want). It may make sense to turn this issue into a Discussion thread because the workaround I have in mind likely isn't something that would be acceptable as a feature within Sphinx.
Ok, and one more thing to check: is it unacceptable in your environment to use hyperlink text fragments to link to the relevant server grouping heading in genindex.html?
(I don't love text fragment links personally, but I did figure that they could be one other path to achieve the result here)
Huh, didn't know that was possible.
Sadly not in this case. The generated docs are both available on an internal server and as standalone on personal computers by pointing a browser at the directory path. Unless Sphinx makes the path to the index available somehow, constructing the correct URL will be difficult and error prone.
Is the relative URL to the index on the server and computers genindex.html for the versions of Sphinx deployed so far?