Finer grained control over domain ToC entries

[AA-Turner]

Follow-up from #10807 and #6316.

Feature or Bugfix

• Feature
• Bugfix

cc @jakobandersen @josephmure @asmeurer

A

[asmeurer]

I can confirm the SymPy docs still build fine with this PR.

[josephmure]

The OpenTURNS doc builds correctly with this PR. Thanks!

[jakobandersen]

Looks good to me, except I suggest having the direction option be called notocentry, which I think provides a more direct association to the toctree directive that it in a sense modifies.

Somehow the changelog should gain an "incompatible changes" entry, where the new configuration option is mentioned to restore the old behaviour, but I guess it's not feasible to retroactively change the 5.2 entries.

Thanks for the quick response.

[AA-Turner]

my concern with notocentry is parsing the phrase for readers unfamilar--as the others (no index, no index entry) use smushedwords I hesitate to use e.g. no-toc-entry.

What would you prefer of either nocontentsentry or no-toc-entry?

A

[AA-Turner]

The OpenTURNS doc builds correctly with this PR. Thanks!

Thank you for testing. I would ask that you consider for a little while keeping the ToC entries enabled in your documentation -- I have found it very useful in reference documentation to be able to jump directly to the object I want, and your readers may do too. I admit to significant bias here, though, as I implemented the feature, and it would be nice for it to be used rather than disabled.

A

[jakobandersen]

my concern with notocentry is parsing the phrase for readers unfamilar--as the others (no index, no index entry) use smushedwords I hesitate to use e.g. no-toc-entry.

What would you prefer of either nocontentsentry or no-toc-entry?

I'm not sure notocentry is that bad, but it's not too important to me. I'd rather go with the current than using dashes.

I think it's a great feature to have the automatic toc entries. The point of the option is that users can enable them when they are ready, and still get the benefit of newer Sphinx versions in general.

[AA-Turner]

Sphinx 5.2.3 has been released.

A

[josephmure]

The OpenTURNS doc builds correctly with this PR. Thanks!

Thank you for testing. I would ask that you consider for a little while keeping the ToC entries enabled in your documentation -- I have found it very useful in reference documentation to be able to jump directly to the object I want, and your readers may do too. I admit to significant bias here, though, as I implemented the feature, and it would be nice for it to be used rather than disabled.

A

We'll certainly test the feature, but I think we'll need a comprehensive redesign of our document to use it effectively.