Sphinx: Generate one TOC per .rst

Question

I am trying to convert GNU Parallel's (boring) POD-html to Sphinx.

I use this index.rst:

.. SPDX-FileCopyrightText: 2021 Ole Tange, http://ole.tange.dk and Free Software and Foundation, Inc.
..
.. SPDX-License-Identifier: GPL-3.0-or-later

.. GNU Parallel documentation master file, created by
   sphinx-quickstart on Sat Jan 23 14:06:27 2021.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to GNU Parallel's documentation!
========================================

.. toctree::
   :maxdepth: 3
   :caption: Contents:

   parallel
   sem
   env_parallel
   parset
   parsort
   parallel_design
   parallel_tutorial
   parallel_alternatives
   parcat
   niceload
   sql


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

It generates amongst other files: https://www.gnu.org/software/parallel/parset.html

The problem here is that I want the left sidebar to only include headings relevant to parset - not to all the other files (e.g. the top link under CONTENTS links to parallel.html) Or at the very least: Insert a header over each new file, so the user can see this links to another command.

I assume I simply need to add some magic to index.rst to tell it only to base CONTENTS on the current file.

(The .rst files are generated from POD using pod2rst - and yes there are a few formatting bugs, but I am not going to maintain the documentation in .rst-format).

score 1 · Answer 1 · answered Jul 12 '21 at 09:56

I found a way to do the suboptimal solution. Make a toctree section for each:

.. toctree::
   :maxdepth: 1
   :caption: parallel

   parallel

.. toctree::
   :maxdepth: 3
   :caption: sem

   sem

.. toctree::
   :maxdepth: 3
   :caption: env_parallel

   env_parallel

This gives a heading for each file.

Sphinx: Generate one TOC per .rst

1 Answers1