Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use xelatex for building PDF in Sphinx 1.5 #2572

Closed
stevepiercy opened this issue May 15, 2016 · 7 comments

Comments

Projects
None yet
2 participants
@stevepiercy
Copy link
Member

commented May 15, 2016

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

This comment has been minimized.

Copy link
Member Author

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?

@bertjwregeer

This comment has been minimized.

Copy link
Member

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.

@stevepiercy

This comment has been minimized.

Copy link
Member Author

commented May 15, 2017

The larger issue is that I could not find any documentation about building PDF, other than what I could divine from reading the make file and conf.py. It made me wonder whether we actually support building PDF, especially when I ran into problems.

Whenever I try to build a PDF locally, I hit a couple dozen warnings/errors, each of which requires me to tap the enter key to dismiss. That's annoying, and did not used to happen in older versions of Pyramid. Most of them are due to unsupported Unicode characters, such as those from tree, but there are a few others that I don't understand, like some directives in the LaTeX preamble. When I comment out those few, then the errors go away, but I don't know whether that would be a good idea for the project.

For Sphinx.tex, is that just setting the minimum version of Sphinx to 1.5.x?

As far as the Unicode characters, I could replace them with something from ASCII.

Oh, and the make files in Sphinx 1.5 are vastly more simple now, although we can continue to use what we have.

Here are excerpts from pyramid.log:

! LaTeX Error: \py@noticestart@warning undefined.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.101 \renewcommand{\py@noticestart@warning}
                                            {\py@heavybox}
? H
Try typing  <return>  to proceed.
If that doesn't work, type  X <return>  to quit.
? 

! LaTeX Error: \py@noticeend@warning undefined.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.102 \renewcommand{\py@noticeend@warning}
                                          {\py@endheavybox}
? 

! LaTeX Error: \py@noticestart@note undefined.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.103 \renewcommand{\py@noticestart@note}
                                         {\py@heavybox}
? 

! LaTeX Error: \py@noticeend@note undefined.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.104 \renewcommand{\py@noticeend@note}
                                       {\py@endheavybox}
? 
! Undefined control sequence.
l.2422 \mainmatter
                  
? 
l.18347 ├-- .coveragerc
                         
? 

! Package inputenc Error: Unicode char ├ (U+251C)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.18348 ├-- CHANGES.txt
                         
? 

! Package inputenc Error: Unicode char ├ (U+251C)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.18349 ├-- MANIFEST.in
                         
? H
Your command was ignored.
Type  I <command> <return>  to replace it with another command,
or  <return>  to continue without it.
? H
Sorry, I already gave what help I could...
Maybe you should try asking a human?
An error might have occurred before I noticed any problems.
``If all else fails, read the instructions.''

? 

! Package inputenc Error: Unicode char ├ (U+251C)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.18350 ├-- myproject
                       
? 

! Package inputenc Error: Unicode char ├ (U+251C)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.18351 ...Zus{}\PYGZus{}init\PYGZus{}\PYGZus{}.py
                                                  
? 

! Package inputenc Error: Unicode char ├ (U+251C)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.18352 \textbar{}   ├-- static
                                   
? 

! Package inputenc Error: Unicode char ├ (U+251C)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.18353 ...r{}   ├-- pyramid\PYGZhy{}16x16.png
                                                  
? 

! Package inputenc Error: Unicode char ├ (U+251C)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.18354 ...{}   \textbar{}   ├-- pyramid.png
                                                  
? 

! Package inputenc Error: Unicode char └ (U+2514)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.18355 ...ar{}   \textbar{}   └-- theme.css
                                                  
? 

! Package inputenc Error: Unicode char ├ (U+251C)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.18356 \textbar{}   ├-- templates
                                      
? 

! Package inputenc Error: Unicode char ├ (U+251C)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.18357 ...   \textbar{}   ├-- layout.jinja2
                                                  
? 

! Package inputenc Error: Unicode char └ (U+2514)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.18358 ... \textbar{}   └-- mytemplate.jinja2
                                                  
? 

! Package inputenc Error: Unicode char ├ (U+251C)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.18359 \textbar{}   ├-- tests.py
                                     
? 

! Package inputenc Error: Unicode char └ (U+2514)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.18360 \textbar{}   └-- views.py
                                     
? 

! Package inputenc Error: Unicode char ├ (U+251C)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.18361 ├-- README.txt
                        
? 

! Package inputenc Error: Unicode char ├ (U+251C)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.18362 ├-- development.ini
                             
? 

! Package inputenc Error: Unicode char ├ (U+251C)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.18363 ├-- production.ini
                            
? 

! Package inputenc Error: Unicode char ├ (U+251C)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.18364 ├-- pytest.ini
                        
? 

! Package inputenc Error: Unicode char └ (U+2514)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.18365 └-- setup.py
                      
? 
@bertjwregeer

This comment has been minimized.

Copy link
Member

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.

@stevepiercy

This comment has been minimized.

Copy link
Member Author

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.

@stevepiercy

This comment has been minimized.

Copy link
Member Author

commented Apr 25, 2018

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

@stevepiercy

This comment has been minimized.

Copy link
Member Author

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)

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

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)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.