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
:noindex: prevents cross-referencing #7052
Comments
The
Unfortunately, it is strongly coupled with cross-reference system. So this is very difficult problem. |
Ideally there would be Perhaps, add new flags
What do you think? |
@vsajip Have you found a workaround in the meantime? |
No, unfortunately not. I think what I suggested is the appropriate fix, but waiting for feedback on this from the maintainers. |
I believe some of the problem may be related to documentation, for what
For the domains declarations that support At this point I can not imagine a use case where suppression of (2) but not (1) makes sense. Do I understand it correctly that you would like to suppress (3) but keep (1) and (2)? (We could also invent a new name for what |
Well, the ability to include/exclude index items is orthogonal to cross-referencing within the documentation. As you've identified, (1) needs to happen always, so that (2) and (3) are not "incidentally" made impossible. (2) is the most useful IMO (follow an intra-document link for more information about something) and (3) is useful but not as much (mainly used when you know the name of what you're looking for). One might want to suppress (3) because it makes the index too voluminous or confusing to include everything that's indexable, for example. The documenter can control (2) by choosing to use a |
new to sphinx and all that, so I can't comment on all these cases. I came across this issue because in our documentation, we have automodules in our RST docs and at the same time have a autodoc generated files that are accessible through the search bar. One of the two needs the :noindex: as told by sphinx error message, but this also removes/prevents anchor links. |
Right, (2) and (3) are of course orthogonal. There are definitely use-cases for suppressing all (e.g., writing example declarations), but I guess not necessarily used that often. Anyway, I guess we are back to looking for a name for the option the suppressed (3) but not (1)? |
I'm not too familiar with autodoc but it doesn't sound like |
I understood it to mean that in the current code base, you can't separate out (2) and (3) - the only thing you have to prevent something appearing in (3) is |
Thank you for your explanation. Yes, both (2) and (3) depend on (1)'s database (the internal index). And the But I understand the idea to disable only (3). So +0 if there is good naming for the option. But we need to keep the name and its behavior of Note: I still don't understand disabling (2) is really needed. So I don't think to add an option to do that at present. |
I agree that there is no strong need to disable (2), except to flag a particular target in the case of ambiguities - which should be a rare case. What about the naming I suggested in the above comment, specifically |
I don't find |
I think we should use a different word for the new option. We already use the "index" at Note: Ideally, it would be best if we can rename |
I'm fine with |
I agree with @tk0miya. +1 for |
If a
:noindex:
flag is added to a directive, it can't be cross-referenced, and no permalink to it is generated.The following ReST:
generates the following HTML:
I would expect
:noindex:
only to result in no index entry, not to prevent cross-referencing or permalinking. The HTML generated for the two class directives should be the same, i.e. the HTML for the Unindexed class should beThe text was updated successfully, but these errors were encountered: