# Use xelatex for building PDF in Sphinx 1.5 #2572

Closed
opened this issue May 15, 2016 · 7 comments

Projects
None yet
2 participants
Member

### stevepiercy commented May 15, 2016 • edited

 Sphinx is going to add xelatex and lualatex builders in Sphinx 1.5. This will make it easier to output Unicode characters like © and ├ from `tree` output for PDF. I surrendered and used `\` for PDF generation on `docs/quick_tutorial/tutorial_approach.rst` and `docs/quick_tutorial/requirements.rst`. Upon release of Sphinx 1.5, it might be a good time to revisit the PDF generation altogether. To try it out: ```\$ \$VENV/bin/pip install git+https://github.com/sphinx-doc/sphinx.git@master # add this to docs/Makefile, making sure you use tabs and not spaces to indent the code .PHONY: xelatexpdf xelatexpdf: \$(SPHINXBUILD) -b latex \$(ALLSPHINXOPTS) \$(BUILDDIR)/latex @echo "Running LaTeX files through xelatex..." \$(MAKE) PDFLATEX=xelatex -C \$(BUILDDIR)/latex all-pdf @echo "xelatex finished; the PDF files are in \$(BUILDDIR)/latex." \$ make xelatexpdf SPHINXBUILD=\$VENV/bin/sphinx-build```

### stevepiercy added a commit to stevepiercy/pyramid that referenced this issue May 15, 2016

``` use characters that don't break the latexpdf builder. See Pylons#2572 ```
``` f3a884f ```

Member Author

### stevepiercy commented May 13, 2017

 Do we have an officially supported method to build a PDF? It seems that Sphinx has moved forward, but our `conf.py` and make files have not kept up. I'm inclined to remove a lot of the latex configuration stuff that was inserted before my time. I don't understand its function. At this point, I would like to either drop the PDF builder or update it so that a PDF can be built without repeatedly hitting return to dismiss warnings. Anyone have thoughts or more information?
Member

### bertjwregeer commented May 15, 2017

 What LaTeX stuff that do you believe is no longer required? Why do you believe it is no longer required? Much of the Sphinx stuff that is currently in `conf.py` is there to do book formatting for the PDF output, as well as change some of the styling to be more pleasing. It looks like the `Sphinx.tex` file no longer has the same defines in it as it had before, so we should update it to the newest version. I wouldn't recommend wholesale removal though.
Member Author

### stevepiercy commented May 15, 2017

Member

### bertjwregeer commented May 15, 2017

 `\py@noticestart@warning` This for instance used to be included in the default `Sphinx.tex` template that Sphinx (version 1.4.x) shipped for their LaTeX support. Our `conf.py` modifies the formatting to allow it to lay out better so that it could be printed as a book. It also used the `book` formatting class from LaTeX. If you downgrade for example to Sphinx version 1.4.9; outside of the UTF-8 character issues the pdf builds without issues. We should figure out what exactly changed and see if it makes sense to convert it over to the new Sphinx version, or if we should instead drop our custom formatting to allow for easier upgrades, and use the default Sphinx template for creating LaTeX and also PDF's.
Member Author

### stevepiercy commented May 15, 2017

 I'd go with the version of Sphinx used by RTD, currently 1.5.3, even though 1.6 is due to be released very soon.

Merged

Member Author

### stevepiercy commented Apr 25, 2018 • edited

I got this working.

## docs/Makefile

Make sure you use tabs and not spaces to indent the code.

```.PHONY: xelatexpdf
xelatexpdf:
\$(SPHINXBUILD) -b latex \$(ALLSPHINXOPTS) \$(BUILDDIR)/latex
@echo "Running LaTeX files through xelatex..."
\$(MAKE) PDFLATEX=xelatex -C \$(BUILDDIR)/latex all-pdf
@echo "xelatex finished; the PDF files are in \$(BUILDDIR)/latex."```

## `conf.py`

Insert these stanzas in the preamble.

```%XeLaTeX packages
\usepackage{xltxtra}
\usepackage{fontspec} %Font package
\usepackage{xunicode}

%Select fonts
\setmainfont[Mapping=tex-text]{nimbusserif}
\setsansfont[Mapping=tex-text]{nimbussans}
\setmonofont{nimbusmono}```

## Build pretty PDF

`\$ make xelatexpdf SPHINXBUILD=\$VENV/bin/sphinx-build`

That yields nice fonts that come with the LaTex Font Catalogue and Unicode character support.

For reference, I got the idea from https://tex.stackexchange.com/a/5445

Member Author

### stevepiercy commented Apr 25, 2018

 Additionally, the following files need to be updated: setup.py (Sphinx >= 1.7.2, != 1.7.3) docs/make_pdf (use xelatexpdf) docs/make_book (use xelatexpdf)

Closed

### stevepiercy added a commit that referenced this issue Apr 26, 2018

``` Bump sphinx to >=1.7.4 ```
```- Closes #3269 and #667
- Paves the way for #2572```
``` f6cb40b ```

Merged

### stevepiercy added a commit to stevepiercy/pyramid that referenced this issue Apr 26, 2018

``` Bump sphinx to >=1.7.4 ```
```- Closes Pylons#3269 and Pylons#667
- Paves the way for Pylons#2572

(cherry picked from commit f6cb40b)```
``` 8766080 ```

Merged

Merged