reStructuredText: Automatic table of contents for standalone .rst file

Question

I'm a Markdown user but recently I came across reStructuredText and I wanted to take advantage of its features to create technical documents in pdf.

I know this markup language is mainly used with Sphinx to create Python package documentation, but I wanted to know if I can also use it outside of Python to create simple pdf documents, just like I would with Markdown via Pandoc.

The problem I'm running into is that I'm using only one .rst file like this which I render to pdf

=====
Title
=====


.. contents::


some text...

Chapter 1
---------

some text...

Chapter 2
---------

some text...

What I would like to do is create a table of contents for this single .rst file, to be converted into PDF, which contains the references of the sections of this page (i.e. the chapters and any sub-chapters and paragraphs). Since I don't have any other external file .. toctree:: doesn't help me and even using .. contents:: I didn't get the desired result (actually I didn't get any table of contents in my final pdf output).

With Markdown this was easy to achieve by using toc: true in the preamble like in this example

---
title: "Title"
toc: true
---

some text...

# Chapter 1


some text...

# Chapter 2

some text...


... and so on

Trying to be clear, this is my project folder structure:

.
├── Makefile
├── test.rst
└── test.pdf

Through the Makefile I convert my .rst file to pdf. This is the source code of my Makefile faithfully inspired by lmullen's idea in which it converts a .md file into .pdf.

The content of my Makefile is as follows:

PDFS := $(patsubst %.rst,%.pdf,$(wildcard *.rst))


all : $(PDFS)

              
%.pdf : %.rst
    pandoc $< -o $@


clean:
    rm $(PDFS)

rebuild : clean all

There's probably a lot to fix here to make it more flexible, but that's what I've managed to do so far.

I am therefore able to leverage the rst markup language to create a pdf content but having no experience with reStructuredText I am unable to create a table of contents for the sections of this .rst file, as I would be able to do using markdown.

I hope the request was clear and that some of you can help me.

Answer 1

It seems to be that Pandoc intentionally ignores the .. contents:: directive in reStructuredText files: https://github.com/jgm/pandoc/issues/4108

Here is a link to an online Pandoc editor showing that no table of contents is written in the output.

Answer 2

As an alternative to Pandoc, you might want to try rst2pdf. It supports the contents directive.

Take a look at the "Structured Document" example here: https://rst2pdf.org/examples.

Answer 3

The Docutils Python package converts a single reStructuredText file into a variety of output formats. It also supports all features of standard reStructuredText including the .. contents:: directive.

So, unless you object to anything based on Python, it seems to be a tool matching the task without the overhead of Sphinx. Save your example totest.rst, say and run rst2latex test.rst > test.tex followed by pdflatex test.tex.

Alternatively use the already mentioned rst2pdf converter that uses Docutils and ReportLab (instead of LaTeX).