Allow explicit markup in toctree directives #2354
Conversation
|
MEMO: Similar to #1800. |
|
Man, somehow I completely missed that in my search for this. D'oh! Either way. :) |
|
Big +1 for this |
This adds support for :ref:`` text in toctree listings in particular, but is reasonably generic. My website, for example, now contains something like .. toctree:: _ :ref:`foo <bar>` baz which renders as one might expect.
|
Just pushed a new commit that's caught up to HEAD. |
|
Kill=for/bar/baz |
|
@MARIOBlueOrigin what? |
|
Kill=foo/bar/baz; |
|
@tk0miya Is there any reason this PR cannot be merged? |
|
I don't have an answer how such reference should be represented in non-HTML formats. In addition, I don't think cross-references are not a part of ToC. So it's strange to define it in toctree directive. |
|
@tk0miya As per #701 (comment), I believe we understand what LaTeX should do when it encounters these TOC entries: it should render the node as an argument to |
|
I think LaTeX is only one example. How about manpage? How about singlehtml? We have many builders (including 3rd party builders) that don't represent ToC trees as link collections. |
|
@tk0miya How about #7913? @whitequark Would something like that work for your needs? |
Rather than the approach taken by sphinx-doc#2354, which would require answering some tricky questions about the entire set of Builders in the known universe, just expose just enough through hooks or overridable routines so that individual instances of Sphinx can splice in their own implementation of this functionality if it is desired.
Rather than the approach taken by sphinx-doc#2354, which would require answering some tricky questions about the entire set of Builders in the known universe, just expose just enough through hooks or overridable routines so that individual instances of Sphinx can splice in their own implementation of this functionality if it is desired.
|
It's apparent that this approach can no longer be considered viable. |
That looks nice! I see the PR is closed, do you still want to pursue the approach? |
|
I don't believe I have the bandwidth to properly modify something as deeply integrated to sphinx as its toctrees. So I hacked around it; see #701 (comment) . I probably should have posted that first before closing the PRs. |
This adds support for :ref:`` text in toctree listings in particular, but is
reasonably generic. My website, for example, now contains something like
which renders as one might expect.