Here's a *crude* first attempt to make Sphinx generate a LaTeX file for
a Sage Quick Reference "card" (http://wiki.sagemath.org/quickref):
* Look below for minor changes to SAGE_DOC/common/builder.py and conf.py .
* Look further for SAGE_DOC/common/quickref.py .
Right now, the quickref builder yields a LaTeX file with a semi-viable
preamble, and
sage -docbuild tutorial quickref
cd SAGE_DOC/output/quickref/en/tutorial
make
yields a messy 3-column landscape-oriented PDF file. I haven't yet
tried to convert an existing card to the ReST format, so I'm not sure
how much of the standard LaTeX translator's HEADER, BEGIN_DOC, and
FOOTER (see quickref.py) is unnecessary. Perhaps a lot.
I'm posting this here in case there's interest. Also, I'm not sure when
I'll be able to return to this in the near future.
Some further possibilities:
* Generating cards from designated [parts of] docstrings.
* A custom layout.html for [on-the-fly] notebook introspection.
* CSS3 columns: http://www.css3.info/preview/multi-column-layout/
* Links to docstrings, and more generally, links among docstrings,
perhaps with js.py's async_request(). Should each worksheet connect to
two instances of sage, one for computations and another for introspection?
diff --git a/doc/common/builder.py b/doc/common/builder.py
--- a/doc/common/builder.py
+++ b/doc/common/builder.py
@@ -232,6 +232,7 @@
json = builder_helper('json')
htmlhelp = builder_helper('htmlhelp')
latex = builder_helper('latex')
+ quickref = builder_helper('quickref')
changes = builder_helper('changes')
linkcheck = builder_helper('linkcheck')
diff --git a/doc/common/conf.py b/doc/common/conf.py
--- a/doc/common/conf.py
+++ b/doc/common/conf.py
@@ -5,6 +5,7 @@
# is relative to the documentation root, use os.path.abspath to make it
# absolute, like shown here.
#sys.path.append(os.path.abspath('.'))
+sys.path.append(os.path.join(SAGE_DOC, 'common'))
# General configuration
# ---------------------
@@ -13,6 +14,9 @@
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc']
+# Custom builder for Sage Quick Reference.
+extensions.append('quickref')
+
if 'SAGE_DOC_JSMATH' in os.environ:
extensions.append('sphinx.ext.jsmath')
else:
--~--~---------~--~----~------------~-------~--~----~
To post to this group, send email to sage-devel@googlegroups.com
To unsubscribe from this group, send email to
sage-devel-unsubscr...@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sage-devel
URLs: http://www.sagemath.org
-~----------~----~----~----~------~----~------~--~---
# -*- coding: utf-8 -*-
"""
Custom LaTeX translator, writer, and builder to generate Sage
Quick Reference "cards."
"""
import os
from os import path
from docutils.io import FileOutput
from docutils.frontend import OptionParser
from sphinx.latexwriter import LaTeXTranslator, LaTeXWriter
from sphinx.builder import LaTeXBuilder
# For convenience, we've included in the comments below the standard
# HEADER, BEGIN_DOC, FOOTER variables from sphinx.latexwriter v0.5.1.
#HEADER = r'''%% Generated by Sphinx.
#\documentclass[%(papersize)s,%(pointsize)s%(classoptions)s]{%(docclass)s}
#%(inputenc)s
#%(fontenc)s
#%(babel)s
#%(fontpkg)s
#%(fncychap)s
#\usepackage{sphinx}
#%(preamble)s
#
#\title{%(title)s}
#\date{%(date)s}
#\release{%(release)s}
#\author{%(author)s}
#\newcommand{\sphinxlogo}{%(logo)s}
#\renewcommand{\releasename}{%(releasename)s}
#%(makeindex)s
#%(makemodindex)s
#'''
QUICKREF_HEADER = r'''%% Generated by Sphinx' Sage Quick Reference builder.
\documentclass[%(papersize)s,%(pointsize)s%(classoptions)s]{%(docclass)s}
%(inputenc)s
%(fontenc)s
%(babel)s
%(fontpkg)s
%(fncychap)s
\usepackage{sphinx}
%(preamble)s
\title{%(title)s}
\date{%(date)s}
\release{%(release)s}
\author{%(author)s}
\newcommand{\sphinxlogo}{%(logo)s}
\renewcommand{\releasename}{%(releasename)s}
%(makeindex)s
%(makemodindex)s
%% Sage quick reference
\usepackage{multicol}
\usepackage[landscape]{geometry}
\newcommand{\ex}{\color{blue}}
\newcommand{\warn}{\bf\color{red}}
\pagestyle{empty}
\advance\topmargin-.9in
\advance\textheight2in
\advance\textwidth3.0in
\advance\oddsidemargin-1.45in
\advance\evensidemargin-1.45in
\parindent0pt
\parskip2pt
%% Section break, dictates column widths?
\newcommand{\hr}{\centerline{\rule{3.5in}{1pt}}}
%% Adjust gap to affect spacing, page count
\newcommand{\sect}[1]{\hr\par\vspace*{2pt}\textbf{#1}\par}
%% Mandatory indentation on subsidiary lines
\newcommand{\skipin}{\hspace*{12pt}}
'''
#BEGIN_DOC = r'''
#\begin{document}
#%(shorthandoff)s
#%(maketitle)s
#%(tableofcontents)s
#'''
QUICKREF_BEGIN_DOC = r'''
\begin{document}
\begin{multicols*}{3}
%(shorthandoff)s
%(maketitle)s
%(tableofcontents)s
'''
#FOOTER = r'''
#%(footer)s
#\renewcommand{\indexname}{%(modindexname)s}
#%(printmodindex)s
#\renewcommand{\indexname}{%(indexname)s}
#%(printindex)s
#\end{document}
#'''
QUICKREF_FOOTER = r'''
%(footer)s
\renewcommand{\indexname}{%(modindexname)s}
%(printmodindex)s
\renewcommand{\indexname}{%(indexname)s}
%(printindex)s
\end{multicols*}
\end{document}
'''
class LaTeXQuickRefTranslator(LaTeXTranslator):
"""
Translates input to LaTeX for Sage Quick Reference PDF files.
We've reimplemented astext() and visit_document() to use
QUICKREF_HEADER, QUICKREF_FOOTER, and QUICKREF_BEGIN_DOC from
above.
"""
def astext(self):
return (QUICKREF_HEADER % self.elements +
self.highlighter.get_stylesheet() +
u''.join(self.body) + QUICKREF_FOOTER % self.elements)
def visit_document(self, node):
self.footnotestack.append(self.collect_footnotes(node))
if self.first_document == 1:
# the first document is all the regular content ...
self.body.append(QUICKREF_BEGIN_DOC % self.elements)
self.first_document = 0
elif self.first_document == 0:
# ... and all others are the appendices
self.body.append('\n\\appendix\n')
self.first_document = -1
# "- 1" because the level is increased before the title is visited
self.sectionlevel = self.top_sectionlevel - 1
class LaTeXQuickRefWriter(LaTeXWriter):
"""
Writes LaTeX for Sage Quick Reference PDF files.
We've reimplemented translate() to use LaTeXQuickRefTranslator.
"""
def translate(self):
visitor = LaTeXQuickRefTranslator(self.document, self.builder)
self.document.walkabout(visitor)
self.output = visitor.astext()
class LaTeXQuickRefBuilder(LaTeXBuilder):
"""
Builds LaTeX output for Sage Quick Reference PDF files.
We've reimplemented write() to use LaTeXQuickRefWriter.
"""
name = 'quickref'
def write(self, *ignored):
# first, assemble the "appendix" docs that are in every PDF
appendices = []
for fname in self.config.latex_appendices:
appendices.append(self.env.get_doctree(fname))
docwriter = LaTeXQuickRefWriter(self)
docsettings = OptionParser(
defaults=self.env.settings,
components=(docwriter,)).get_default_values()
self.init_document_data()
for entry in self.document_data:
docname, targetname, title, author, docclass = entry[:5]
toctree_only = False
if len(entry) > 5:
toctree_only = entry[5]
destination = FileOutput(
destination_path=path.join(self.outdir, targetname),
encoding='utf-8')
self.info("processing " + targetname + "... ", nonl=1)
doctree = self.assemble_doctree(docname, toctree_only,
appendices=(docclass == 'manual') and appendices or [])
self.post_process_images(doctree)
self.info("writing... ", nonl=1)
doctree.settings = docsettings
doctree.settings.author = author
doctree.settings.title = title
doctree.settings.docname = docname
doctree.settings.docclass = docclass
docwriter.write(doctree, destination)
self.info("done")
def setup(app):
app.add_builder(LaTeXQuickRefBuilder)
