Handle restructured text/sphinx toctree construct in file previews

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

• Close this issue

We are using restructuredtext and sphinx to write our documentation. Because of this, we have a bunch of index.rst files with toctree blocks in them:

.. toctree::                                                                     
   :maxdepth: 3                                                                  
                                                                                 
   intro                                                                         
   architecture                                                                  
   getting-started

This construct "links" to other documents (in this case, it would be intro/index.rst or intro.rst, etc.) relative to the current directory, using the title of the document as the link label, like this:

<ul>
    <li><a href="intro.rst">Introduction</a></li>
    <li><a href="architecture/index.rst">Architecture</a></li>
    <li><a href="getting-started/index.rst">Getting Started With Gitlab</a></li>
</ul>

It would loosely map to the way people often create README.md file with links to other documents, and it would make Sphinx documentation embedded in repositories insta-browseable using the Repository view in GitLab.

So far it does not seem that this directive is being processed at all, so it is ignored and does not appear at all in the rendering made by Gitlab.

See reference here: http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree

The TOC tree support in Sphinx is pretty extensive, but IMO a very basic support would be enough here.

Proposals

For ReStructuredText files, one of the following proposals could be implemented:

1. The .. toctree:: block could be displayed in a "raw" way instead of being silently ignored
2. The .. toctree:: block could be displayed in a "raw" way, but with the file names being transformed into relative links, as it is expected that it will either lead to a .rst or .md file, or to a directory
3. The .. toctree:: block could be transformed into a proper table of contents. This might be harder to achieve in a general way as the result depends on other files, especially if multiple levels of TOC are supported.