relative links in toctree

[shimizukawa]

I'd like to use relative URLs in toctrees, but can't figure out how. It seems right now I have the choice between either internal links (where the target is another document), or an (absolute) URL. The latter is identified by means of a sphinx.util.url_re.

Is there a way to have a toctree entry use a relative link, such that the generated html contains 'href=".../some/path.html"' ?

(If it isn't yet supported, perhaps a new pseudo-schema would work, such as 'relative:.../some/path.html', from which the 'relative:' would then be stripped off during html generation ?)

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/701
• Originally reported by: Anonymous
• Originally created at: 2011-05-22T03:17:53.521

[shimizukawa]

From Anonymous on 2012-04-18 14:10:29+00:00

I would also like to use relative document locations that are not within the directory tree housing conf.py. For instance, see my stack overflow question:

http://stackoverflow.com/questions/10199233/can-sphinx-link-to-documents-that-are-not-located-in-directories-below-the-root

[shimizukawa]

From rdburns on 2012-04-18 14:12:13+00:00

That previous comment was me, forgot to login.

[shimizukawa]

From Mac Ryan on 2012-08-02 10:26:08+00:00

I second this request (just in case the number of people requesting this feature influences the priority queue...). :)

[shimizukawa]

From Dmitriy Kruglov on 2012-09-13 09:35:01+00:00

One more vote to have the feature.

[shimizukawa]

From Marcus Lindblom Sonestedt on 2012-10-17 10:50:22+00:00

We'd like this too! :)

[shimizukawa]

From Gringo Suave on 2012-12-14 03:35:35+00:00

Bitbucket demands I keep my readme in the root, sphinx demands I keep it in ./docs ... what to do? I'd use a filesystem link but project needs to be able to work under Windows and hg doesn't support links there.
I'll have to keep two copies in the repo unless anyone has a better idea. :(

[shimizukawa]

From Thibault Kruse on 2013-01-30 12:25:54+00:00

+1

[shimizukawa]

From Georg Brandl on 2013-01-31 07:37:34+00:00

You can put it in the root and use ".. include:: ../README" from a file in "docs", like Sphinx does with CHANGES.

[shimizukawa]

From mears on 2013-08-27 06:48:18+00:00

I'd like to see this implemented as well

[shimizukawa]

From Adam Siembida on 2014-04-01 22:06:49+00:00

This would be great to have. I know you can use symlinks to files shared between projects, but Windows doesn't have the greatest support for that.

[dghubble]

I wish there was a way to put a relative link in a toctree entry too! I have some plain files (they happen to be javadocs, but could be anything generated by some non-sphinx system). I place files in the build directory with html_extra_path and tried adding a link to them in a number of ways:

.. toctree::
   :maxdepth: 2

   `javadoc/index.html`
    :ref:`javadoc/index.html`
    Javadoc <//javadoc/index.html>
    Javadoc <://javadoc/index.html>
    `Javadoc <javadoc/index.html>`
    self/javadoc/index.html
    :download:`javadoc/index.html`

Also tried with extlink, but none of these attempts seem to work.

Reading through the source, the simplest change might be to start treating // as the prefix for relative url and treating it specially in other.py and environment.py? The current implementation checks for a schema with re.compile(r'(?P<schema>.+)://.*') so I don't think relative links are possible right now.

Just want a relative anchor tag at the end of the day :(

[atodorov]

Basically me too.

I've tried:

:doc:`../tests/README.rst`

which didn't work of course.

[shimizukawa]

@atodorov

You can't use :doc: role in the toctree directive. You should write as:

.. toctree::

   ../tests/README

One more rule is exist. You can not reference to out of sphinx project directory by using toctree directive (and :doc: role).

[Swader]

+1 for relative links in toctree. Sometimes I have custom named anchors in text I want to link to from the toctree, but they don't auto-render because they're not headings, and putting headings near them would severely uglify the documentation.

[Laufire]

+1.

Edit: Later, I found that the entries in the toctree-s are not file paths, but names of documents. So relative includes might not be possible here (as those aren't file paths). We need to create a separate document (an RST file inside the docs dir), to hold the contents, which need to be indexed. And include the name of the document in a toctree.

Example:

In new_doc.rst:

.. include::  ../rel_include_1.rst
.. include::  ../some_dir/rel_include.rst

An in index.rst

.. toctree::a
    :maxdepth: 2

    new_doc

I also suppose that, it might be hard to have relative includes, without creating new documents. As, sphinx has to render the docs in other formats, which might not have the concept of relative includes.

[Swader]

I have solved this issue with a workaround using a custom role and CSS. Described in detail here.

[JanC]

+1 for this feature :/

[mikepurvis]

+1

Is the issue here primarily technical or philosophical?

[tk0miya]

Now we have two pull requests to improve this; #1800 and #2354. And I can understand all your request and I agree with that. But before merging them, we have to discuss the behavior on non HTML builders.

If we add relative links or internal references to toctree, how should they be represented in PDF? How about epub and other formats?

Now we can use URLs in toctree directive like following:

.. toctree::

   some/document
   http://sphinx-doc.org/

But these URLs are ignored by some builders; singlehtml, latex, man, texinfo and so on. It seems URLs are removed on concatenation documents into single file (.tex, .1, .texi, etc.). Is this expected behavior? And what is expected for new relative links and internal references?

I wonder these are really a part of "Table of Contents". If true, there might be a good representation for each formats.

[nwf]

2354 internally uses a generic Node object and builds a compact_paragraph when constructing the TOC structure. There's nothing builder-specific about it and I should hope that the builders continue to render compact_paragraphs as they usually do.

1800 explicitly constructs a reference object, as it is limited to such.

The URL issue is orthogonal and happens with the existing implementation; do these problematic builders not understand URLs in general and so delete them throughout or something?

In any case, please do not make these builders blockers for merging one of #1800 or #2354, which seem to me strict improvements on the existing implementation. (I'd prefer the latter, as I wrote it and it's a smaller patch providing a more generic mechanism, but I won't complain if it's the former.)

[tk0miya]

Did you try to build latex, singlehtml or others? On building these formats, the toctree nodes are removed to concatenate documents to single file. Then no :ref:s are appeared in table of contents on these formats.

In addition, these builders does not call BuildEnvironment.resolve_toctree. so toctree nodes never be expanded to compact_paragraph.

[h2non]

It's genuinely annoying that there's no way to create or consume relative links in toctree yet.

[ax3l]

I worked around this today by creating a symlink inside my rst sources via ln -s:

cd doc/source
ln -s ../../somedir somedir

.. toctree::

   somedir/README

be aware that you can commit symlinks in git.

[bilderbuchi]

Note that that probably won't work on Windows.

[nwf]

For the LaTeX builder, I think LaTeX's \addcontentsline command could be coerced into service, though it would have to be emitted at the correct point in the resulting document. I have no idea how singlehtml does its thing, but I assume the mechanism for getting the LaTeX builder to emit \addcontentsline could be ported over.

[jfbu]

@nwf I have read the thread and don't quite get if for LaTeX the matter is to include in the produced PDF a link, from the TOC, to some external resource. If that is what is at stake, it can be achieved using a suitable \addtocontents, at a suitable location in the document (as you said). But one can not use \addcontentsline because the latter is patched by hyperref to create internal hyperlinks, and can only end up in some link from the TOC to some internal location in the document which itself could be a link to some external resource. (hyperref has theoretical support for nested links, but afaik the pdflatex do not support them). Thus we would end up in situation somewhat like commented above, which is to create section headings especially for the external links.

Using \addtocontents we can put arbitrary material in the PDF tocs, and that could be a link to some external resource. But there will be some complications because TOCs in LaTeX are indented, according to current sectioning level, but this is hardcoded in the LaTeX source for the document class (say book or report) and re-issued at each line done in the TOC. Unfortunately the LaTeX code for this is tied with other things like issuing dots all the way to the page number, so pretending being a section or subsection for the sake of getting the correct indentation brings us to other problems of avoiding these things. We can hardcode the indentation but that will tie us to book or report class and anyhow we have to know if we should use the one for section or subsection or chapter etc...

Anyway to sum up, if some kind of node is provided to the LaTeX writer of the type "put at the corresponding location of the PDF TOC an hyperlink to this external ressource", then yes this can be done with some amount of fiddling with \addtocontents.

I forgot to say that the LaTeX builder does not emit \addcontentsline: it emits \chapter, \section, etc.. and it is those which emit the suitable \addcontentsline when the LaTeX document is compiled into PDF, via a multi-pass system which involves both the .aux and the .toc auxiliary files. The \tableofcontents macro will read the .toc file which contains the typesetting instructions for the PDF toc. And hyperref patches the whole thing in order to get the TOC entries be hyperlinked and also in order to create PDF bookmarks as well (using one more auxiliary file).

[simingy]

+1

[rdburns]

+1

[nwf]

The +1s don't do anyting but aggrivate those of us watching the issue for update. Please don't.

[khaeru]

For anyone washing up here after 4 or 8 years: a simple solution is to write a crude Sphinx extension that copies the desired files into the source tree, and then .gitignore those files.

https://gist.github.com/khaeru/3185679f4dd83b16a0648f6036fb000e

[NumesSanguis]

Copy from https://github.com/readthedocs/recommonmark/issues/191

---

Many Python repositories have a structure similar to:

project/
  docs/
    conf.py
    index.rst
  src/
  README.md

There is no clear instruction on how to including this README.md formatted as Markdown as part of Sphinx, while this is a common occurrence. Online certain solutions can be found:

1. Use .. include:: ../README.md in a readme_link.rst file. Problem: Parses the .md file as RST
2. Add paths to sys.path in conf.py like: sys.path.insert(0, os.path.abspath('..')) Problem: Somehow this doesn't work for me
3. Use a symlink to the README.md Problem: Is not cross-platform (does not work on Windows)
4. Copy the file on make time with a function, as suggested by @khaeru. Problem: Far from ideal, needlessly making files.
5. Use M2R with .. mdinclude:: ../README.md; Only option working for me. Problem: Using extensions = ['m2r', 'recommonmark'] (or reversed list) gives the error: source_suffix '.md' is already registered in the m2r library.

• Would it be possible to support a similar .. mdinclude like M2R?
• Or have .. include:: first check the extension before parsing?
• Or what other clean solution does exist to include a README.md from a parent directory?

[nwf]

@NumesSanguis I believe you are lost. That seems like an entirely separate issue.

[tk0miya]

As nwf said, your comment is not related with this issue at all. Please post a new issue.

Note: At present, Sphinx does not support such feature. But it is much worthy if we support source files outside sphinx project like README.

[NumesSanguis]

I'm sorry, I had many tabs open and found a related issue to my problem before (https://github.com/sphinx-doc/sphinx/issues/2840), but due to seeing a relative path in the OP's question .../some/path, I mistakenly remembered this to be the relevant issue.

I made a new issue for my problem: https://github.com/sphinx-doc/sphinx/issues/7000

[nwf]

Well, I think, after #2354 and #7913, I'm giving up on trying to get any solution to this merged. The toctree is pretty well central to the whole of sphinx, so I understand the hesitation to change it. Instead, I've taken the evening to come up with a truly gross workaround: a ReST directive that synthesizes a hidden toctree and generates the list itself. Limited to :maxdepth: of 1, and doesn't make sense to be :hidden:. https://gist.github.com/nwf/8a1f1d2c48b32d7b457ca8ad2f15d589 ; feedback welcome. Use as

.. toctreeish::

   hocus
   _ :ref:`abra <ca#dabra>`
   pocus

[RabidCicada]

@tk0miya , similar to my comments on #7336 :

Is there a chance that you can:

• suggest a positive path forward for implementing a solution that would be notionally acceptable to you for this issue? There's been a couple tries but it seems like it's pretty difficult to get a yes from you :)

[jmcgeheeiv]

A clever hack on Stack Overflow notes that since any link containing http:// will satisfy Sphinx, this will work:

Downloads <../downloads#http://>

The author notes that this is "one of the hackiest ways possible." Indeed. But it does work.

[nwf]

The fact that sphinx is willing to accept absolute links in its toctree must baffle the LaTeX builder just as much as any of the proposals to address this issue... and indeed, a quick test suggests that the LaTeX builder completely ignores them. There seems to be no open issue for what surely must be considered a defect; I cannot help but feel as if #2354 and #7913 were held to significantly higher standards than the existing code base.

[michaelGonzalez1812]

I would like to have this functionality too.

[silopolis]

So long modular docs! 😭

Please, this would open world of possibilities 🙏

TY J