Creating minimal LaTeX syntax from reStructuredText with docutils

Question

I'm making a Python script that takes several text files with reStructuredText syntax and creates one single LaTeX file with Docutils. Everything works great except Docutils creates a lot of extra syntax I don't need.

For example with a simple subsection Docutils will write

\subsection*{\phantomsection%
About%
\addcontentsline{toc}{subsection}{About}%
\label{about}%

when I only need

\subsection{About}

I've seen that Pandoc doesn't create as much extra syntax, but this doesn't support CSV tables so I can't use it for my project.

I've looked through all the docutils settings and I can't really find any options to limit the output. Is there anyway I set up Docutils to only create the syntax I want?

Not a full answer, but take a look at this blog post, which describes how to modify the HTML output to remove extraneous markup from the section titles. See, in particular, the parts about the functions visit_section and depart_section. It shouldn't be too much of a stretch to modify this for LaTeX output. — Chris

Chris Chris · Accepted Answer · 2012-04-24T16:41:20

Further to my comment, it should be possible to subclass docutils.writers.latex2e.Writer and docutils.writers.latex2e.LaTeXTranslator to customise the output of the docutils LaTeX writer, in a manner similar to this blog post, which describes how to customise the HTML writer. However, looking through docutils.writers.latex2e.LaTeXTranslator this looks a lot more complicated than the HTML writer.

An alternative method would be to just modify these classes. To achieve the output you want simply do the following (note, this is for docutils 0.8.1):

Backup the directory path/to/docutils/writers/latex2e
Modify path/to/docutils/writers/latex2e/__init__.py as follows
1. in the method LaTeXTranslator.visit_title replace the line (line 2870)
```
pdfanchor = '\\phantomsection%\n  '
```
  with
```
pdfanchor = ''
```
2. in the method LaTeXTranslator.visit_title replace the line (line 2878)
```
self.context.append(self.bookmark(node) + '}\n')
```
  with
```
self.context.append('}\n')
```

Note: It is far better to subclass docutils.writers.latex2e.Writer and docutils.writers.latex2e.LaTeXTranslator if possible so that you can benefit from any changes made to these classes in future versions of docutils. The above method works but may need to be changed in future versions.

Creating minimal LaTeX syntax from reStructuredText with docutils

1 Answers