Merge pull request #3288 from stevepiercy/docs-2572-support-xelatex

support xelatex as a PDF and to render Unicode characters
Closes #2572

6 files changed, 39 insertions, 66 deletions

diff --git a/docs/Makefile b/docs/Makefile
index 411ff35df..91f36aefc 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -12,7 +12,7 @@ PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html text web pickle htmlhelp latex latexpdf changes linkcheck epub doctest
+.PHONY: help clean html text web pickle htmlhelp latex latexpdf xelatexpdf changes linkcheck epub doctest
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -22,6 +22,7 @@ help:
 	@echo "  htmlhelp   to make HTML files and a HTML help project"
 	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  xelatexpdf to make LaTeX files and run them through xelatex"
 	@echo "  changes    to make an overview over all changed/added/deprecated items"
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  epub       to make an epub"
@@ -30,6 +31,12 @@ help:
 clean:
 	-rm -rf $(BUILDDIR)/*
 
+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."
+
 html:
 	mkdir -p $(BUILDDIR)/html $(BUILDDIR)/doctrees
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@@ -68,7 +75,7 @@ latex:
 	cp _static/latex-note.png $(BUILDDIR)/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make latexpdf' to build a PDF file from them."
+	@echo "Run \`make xelatexpdf' to build a PDF file from them."
 
 latexpdf:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
diff --git a/docs/conf.py b/docs/conf.py
index 5d68a73a3..80585b336 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -53,7 +53,6 @@ extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
-    'sphinx.ext.todo',
     'sphinx.ext.viewcode',
     'sphinxcontrib.autoprogram',
     # enable pylons_sphinx_latesturl when this branch is no longer "latest"
@@ -124,9 +123,6 @@ exclude_patterns = ['_themes/README.rst', ]
 # unit titles (such as .. function::).
 add_module_names = False
 
-# Add support for todo items
-todo_include_todos = True
-
 # The name of the Pygments (syntax highlighting) style to use.
 #pygments_style = book and 'bw' or 'tango'
 if book:
@@ -223,6 +219,17 @@ latex_domain_indices = False
 _PREAMBLE = r"""
 \usepackage[]{geometry}
 \geometry{bindingoffset=0.45in,textheight=7.25in,hdivide={0.5in,*,0.75in},vdivide={1in,7.25in,1in},papersize={7.5in,9.25in}}
+
+%XeLaTeX packages
+\usepackage{xltxtra}
+\usepackage{fontspec} %Font package
+\usepackage{xunicode}
+
+%Select fonts
+\setmainfont[Mapping=tex-text]{nimbusserif}
+\setsansfont[Mapping=tex-text]{nimbussans}
+\setmonofont{nimbusmono}
+
 \hypersetup{
     colorlinks=true,
     linkcolor=black,
@@ -279,14 +286,6 @@ _PREAMBLE = r"""
 \definecolor{VerbatimColor}{rgb}{1,1,1}
 \definecolor{VerbatimBorderColor}{rgb}{1,1,1}
 
-% mcdonc commented as part of lazy pdf fixing (pdf_rendering_fixes branch)
-% \makeatletter
-% \renewcommand{\py@noticestart@warning}{\py@heavybox}
-% \renewcommand{\py@noticeend@warning}{\py@endheavybox}
-% \renewcommand{\py@noticestart@note}{\py@heavybox}
-% \renewcommand{\py@noticeend@note}{\py@endheavybox}
-% \makeatother
-
 % icons in note and warning boxes
 \usepackage{ifthen}
 
@@ -323,8 +322,6 @@ _PREAMBLE = r"""
 
 latex_elements = {
     'preamble': _PREAMBLE,
-#     mcdonc commented as part of lazy pdf fixing (pdf_rendering_fixes branch)
-#    'wrapperclass': 'book',
     'date': '',
     'releasename': 'Version',
     'title': r'The Pyramid Web Framework',
@@ -348,18 +345,6 @@ def frontmatter(name, arguments, options, content, lineno,
                 content_offset, block_text, state, state_machine):
     return [nodes.raw(
         '',
-        r"""
-% mcdonc commented as part of lazy pdf fixing (pdf_rendering_fixes branch)
-% \frontmatter
-% prevent part/chapter/section numbering
-% \setcounter{secnumdepth}{-2}
-% suppress headers
-% \pagestyle{plain}
-% reset page counter
-% \setcounter{page}{1}
-% suppress first toc pagenum
-% \addtocontents{toc}{\protect\thispagestyle{empty}}
-""",
         format='latex')]
 
 
@@ -367,20 +352,6 @@ def mainmatter(name, arguments, options, content, lineno,
                content_offset, block_text, state, state_machine):
     return [nodes.raw(
         '',
-        r"""
-% mcdonc commented as part of lazy pdf fixing (pdf_rendering_fixes branch)
-% \mainmatter
-% allow part/chapter/section numbering
-% \setcounter{secnumdepth}{2}
-% get headers back
-% \pagestyle{fancy}
-% \fancyhf{}
-% \renewcommand{\headrulewidth}{0.5pt}
-% \renewcommand{\footrulewidth}{0pt}
-% \fancyfoot[C]{\thepage}
-% \fancyhead[RO]{\rightmark}
-% \fancyhead[LE]{\leftmark}
-""",
         format='latex')]
 
 
@@ -388,11 +359,6 @@ def backmatter(name, arguments, options, content, lineno,
               content_offset, block_text, state, state_machine):
     return [nodes.raw(
         '',
-        r"""
-% mcdonc commented as part of lazy pdf fixing (pdf_rendering_fixes branch)
-% \backmatter
-% \setcounter{secnumdepth}{-1}
-        """,
         format='latex')]
 
 
diff --git a/docs/make_book b/docs/make_book
index 94e249441..c3d3743ae 100755
--- a/docs/make_book
+++ b/docs/make_book
@@ -1,4 +1,4 @@
 #!/bin/sh
-make clean latex SPHINXBUILD=../env/bin/sphinx-build BOOK=1
+make clean xelatexpdf SPHINXBUILD=../env/bin/sphinx-build BOOK=1
 cd _build/latex && make all-pdf
 
diff --git a/docs/make_pdf b/docs/make_pdf
index 6c9863bc9..6cf0ff726 100755
--- a/docs/make_pdf
+++ b/docs/make_pdf
@@ -1,4 +1,4 @@
 #!/bin/sh
-make clean latex SPHINXBUILD=../env/bin/sphinx-build
+make clean xelatexpdf SPHINXBUILD=../env/bin/sphinx-build
 cd _build/latex && make all-pdf
 
diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst
index 6bb12c984..29f263176 100644
--- a/docs/quick_tutorial/requirements.rst
+++ b/docs/quick_tutorial/requirements.rst
@@ -79,15 +79,15 @@ will reside as we proceed through the tutorial:
 
 .. code-block:: text
 
-    `── ~
-        `── projects
-            `── quick_tutorial
-                │── env
-                `── step_one
-                    │── intro
-                    │   │── __init__.py
-                    │   `── app.py
-                    `── setup.py
+    ~
+    └── projects
+        └── quick_tutorial
+            ├── env
+            └── step_one
+                ├── intro
+                │   ├── __init__.py
+                │   └── app.py
+                └── setup.py
 
 For Linux, the commands to do so are as follows:
 
diff --git a/docs/quick_tutorial/tutorial_approach.rst b/docs/quick_tutorial/tutorial_approach.rst
index 8da9f71b3..cbc5c3449 100644
--- a/docs/quick_tutorial/tutorial_approach.rst
+++ b/docs/quick_tutorial/tutorial_approach.rst
@@ -23,14 +23,14 @@ below:
 .. code-block:: text
 
     quick_tutorial
-        │── env
-        `── request_response
-            `── tutorial
-            │   │── __init__.py
-            │   │── tests.py
-            │   `── views.py
-            │── development.ini
-            `── setup.py
+    ├── env
+    └── request_response
+        ├── tutorial
+        │   ├── __init__.py
+        │   ├── tests.py
+        │   └── views.py
+        ├── development.ini
+        └── setup.py
 
 Each of the directories in our ``quick_tutorial`` workspace (e.g., ``request_response``) is a *Python
 project* (except as noted for the ``hello_world`` step). The ``tutorial``