1

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.

UzbeKistaN
  • 33
  • 4
  • Do you use Sphinx? Or Pandoc? Which tool do you intend to use to generate the PDF? – sinoroc Mar 20 '23 at 09:56
  • I was planning to convert it with Pandoc via a Makefile. So without using Sphinx, although I'd be glad to know if something like this can be achieved easily with Sphinx as well. – UzbeKistaN Mar 20 '23 at 12:11
  • I've edited my post above to describe my current workflow. I hope it is clearer now. – UzbeKistaN Mar 20 '23 at 22:14
  • Your question does not show how you use the `contents` directive. This should work, if not, then maybe it is a *Pandoc* bug. If you have a GitHub account, you could create a ***gist*** with a minimal `.rst` document showing the issue. – sinoroc Mar 20 '23 at 22:20
  • I did create a ***gist***, and for me there was no issue, GitHub was able to render a table of contents with the `contents` directive. – sinoroc Mar 20 '23 at 22:26
  • I edited the post again inserting the `.. contents::`, maybe I wrote it wrong, I don't know. Or as you say it's a pandoc bug. In fact, I forgot to mention that when I execute the `make` command on the terminal, I get warnings: `pdflatex: major issue: So far, you have not checked for MiKTeX updates.` Where can I see the results of your `gist`? – UzbeKistaN Mar 21 '23 at 08:41
  • 1
    Seems like it's a *pandoc* limitation: https://github.com/jgm/pandoc/issues/4108 -- I recommend you rewrite your question and make it clear that you are working with pandoc, because as it is now, your question has a lot of text but still does not say clearly that you are working with pandoc, it is only when reading the Makefile that one can know that. Really we do not need the Markdown or the Makefile (we need the pandoc command though). Also if you do not use Sphinx then no need to mention it. Really I recommend you keep your question simple and straight to the point. – sinoroc Mar 21 '23 at 09:17

2 Answers2

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.

sinoroc
  • 18,409
  • 2
  • 39
  • 70
0

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.

mzjn
  • 48,958
  • 13
  • 128
  • 248
  • rst2pdf also provides a PDF extension for Sphinx: https://rst2pdf.org/static/manual.html#sphinx. – mzjn Mar 30 '23 at 11:46