diff options
| author | milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2009-02-24 11:40:50 +0000 |
|---|---|---|
| committer | milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2009-02-24 11:40:50 +0000 |
| commit | 17b8a432d43e18bec738fbec1ebd2cca1ebcf041 (patch) | |
| tree | bbdad678bad69c9f957066e2a2d1c74f7b2fa4d7 /sandbox/code-block-directive | |
| parent | 3eeffd4ba5169690bf321b6a96a1e814e74e259d (diff) | |
| download | docutils-17b8a432d43e18bec738fbec1ebd2cca1ebcf041.tar.gz | |
sandbox/code-block-directive: Add LaTeX front end, update
documentation and examples
git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@5873 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
Diffstat (limited to 'sandbox/code-block-directive')
22 files changed, 462 insertions, 1194 deletions
diff --git a/sandbox/code-block-directive/README.txt b/sandbox/code-block-directive/README.txt index 6ffe7e4dd..689a387c6 100644 --- a/sandbox/code-block-directive/README.txt +++ b/sandbox/code-block-directive/README.txt @@ -7,39 +7,42 @@ Proposal for a code-block directive in docutils :Author: Günter Milde :Contact: milde@users.berlios.de :Date: $Date$ +:Copyright: © 2007, 2009 G. Milde, + Released without warranties or conditions of any kind + under the terms of the Apache License, Version 2.0 + http://www.apache.org/licenses/LICENSE-2.0 This sandbox project contains experimental code and documentation related to -the proposal for syntax highlight of source code in docutils using a +the proposal for syntax highlight of source code in docutils using a "code-block" directive. See `<docs/syntax-highlight.html>`_ for a full description. -`<rst2html-highlight>`_ +`<rst2html-highlight>`_ front end for reStructuredText -> HTML conversion supporting the "code-block" directive. +`<rst2latex-highlight>`_ + front end for reStructuredText -> LaTeX conversion supporting the + "code-block" directive. + `<data>`_ - Style sheets + Style sheets. `<docs>`_ Documentation, concepts, discussion, examples... - `<docs/pygments_code_block_directive.py>`_ - Working example: defines and registers a - code-block directive using the Pygments_ syntax highlighter. - - `<docs/pygments_code_block_directive-bunt.py.htm>`_ - Colourful literal code (maybe outdated). - -`<tools>`_ - Alternative (legacy) front ends, - script for interactive testing. - - -.. References +`<pygments_code_block_directive.py>`_ + Working example: defines and registers a + code-block directive using the Pygments_ syntax highlighter. -.. _pygments: http://pygments.org/ +`<tools/test_pygments_code_block_directive.py>`_ + Script for interactive testing. +`<tools/pygments-enhanced-front-ends/>`_ + Legacy front ends, +.. References +.. _pygments: http://pygments.org/ diff --git a/sandbox/code-block-directive/data/pygments-default.sty b/sandbox/code-block-directive/data/pygments-default.sty index 865ff86f8..45cc0363e 100644 --- a/sandbox/code-block-directive/data/pygments-default.sty +++ b/sandbox/code-block-directive/data/pygments-default.sty @@ -1,28 +1,38 @@ +% pygments-default.sty +% ******************** +% % Stylesheet for pygments enhanced reStructured Text % ================================================== -% -% :Author: Guenter Milde -% :Copyright: 2007 G. Milde -% This stylesheet is released under the GPL v. 2 or later -% -% This stylesheet provides syntax highlight for documents generated with a -% pygments_ enhanced reStructured Text -> html converter. -% -% This is an outdated style sheet for the legacy front end. % -% https://sourceforge.net/tracker/?func=detail&atid=422030&aid=2518379&group_id=38414 - +% :Author: Günter Milde +% :Contact: milde@users.berlios.de +% :Revision: $Revision: 5534 $ +% :Date: $Date: 2005-06-28$ +% :Copyright: © 2007, 2009 G. Milde, +% Released without warranties or conditions of any kind +% under the terms of the Apache License, Version 2.0 +% http://www.apache.org/licenses/LICENSE-2.0 +% +% This example style sheet provides syntax highlight for documents generated +% with the legacy front end `rst2latex-pygments`.. +% +% (For the recommended front end `rst2latex-highlight` use +% ``pygments-docutilesroles.sty``.) +% % Separate paragraphs by vertical space % ------------------------------------- +% +% This is not needed for syntax highlight, but usually a good idea for +% documents with lots of source code. +% :: -\setlength{\parindent}{0em} -\setlength{\parskip}{1ex} +\usepackage{parskip} % Colour code blocks % ------------------ -% -% Pygments_ has an option to generate stylesheets for html and latex. -% The following code is generated with the command +% +% Pygments has an option to generate stylesheets for html and latex. +% The following code is based on the output of the command % `pygmentize -S default -f latex`:: \usepackage{fancyvrb} @@ -31,60 +41,60 @@ \newcommand\at{@} \newcommand\lb{[} \newcommand\rb{]} -\newcommand\Cba[1]{\textcolor[rgb]{0.67,0.13,1.00}{\textbf{#1}}} -\newcommand\Caz[1]{\textcolor[rgb]{0.00,0.25,0.82}{#1}} -\newcommand\Cay[1]{\textcolor[rgb]{0.67,0.13,1.00}{#1}} -\newcommand\Cax[1]{\textcolor[rgb]{0.00,0.63,0.00}{#1}} -\newcommand\Cbc[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} -\newcommand\Cas[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} -\newcommand\Car[1]{\textcolor[rgb]{0.72,0.53,0.04}{#1}} -\newcommand\Caq[1]{\textcolor[rgb]{0.73,0.27,0.27}{\textit{#1}}} -\newcommand\Cap[1]{\textcolor[rgb]{0.72,0.53,0.04}{#1}} -\newcommand\Caw[1]{\textcolor[rgb]{0.67,0.13,1.00}{\textbf{#1}}} -\newcommand\Cav[1]{\textcolor[rgb]{0.60,0.60,0.60}{\textbf{#1}}} -\newcommand\Cau[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} -\newcommand\Cat[1]{\textcolor[rgb]{0.67,0.13,1.00}{\textbf{#1}}} -\newcommand\Cak[1]{\textbf{#1}} -\newcommand\Caj[1]{\textcolor[rgb]{0.73,0.40,0.53}{#1}} -\newcommand\Cai[1]{\textcolor[rgb]{0.72,0.53,0.04}{#1}} -\newcommand\Cah[1]{\textcolor[rgb]{0.63,0.63,0.00}{#1}} -\newcommand\Cao[1]{\textcolor[rgb]{0.53,0.00,0.00}{#1}} -\newcommand\Can[1]{\textcolor[rgb]{0.00,0.50,0.00}{#1}} -\newcommand\Cam[1]{\textcolor[rgb]{0.73,0.40,0.13}{\textbf{#1}}} -\newcommand\Cal[1]{\textcolor[rgb]{0.67,0.13,1.00}{\textbf{#1}}} -\newcommand\Cac[1]{\textcolor[rgb]{0.73,0.27,0.27}{#1}} -\newcommand\Cab[1]{\textit{#1}} -\newcommand\Caa[1]{\textcolor[rgb]{0.50,0.50,0.50}{#1}} -\newcommand\Cag[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} -\newcommand\Caf[1]{\textcolor[rgb]{0.00,0.53,0.00}{\textit{#1}}} -\newcommand\Cae[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} -\newcommand\Cad[1]{\textcolor[rgb]{0.73,0.27,0.27}{#1}} -\newcommand\Cbb[1]{\textcolor[rgb]{0.73,0.27,0.27}{#1}} -\newcommand\CaZ[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} -\newcommand\CaY[1]{\textcolor[rgb]{0.00,0.00,0.50}{\textbf{#1}}} -\newcommand\CaX[1]{\textcolor[rgb]{0.00,0.50,0.00}{\textbf{#1}}} -\newcommand\Cbd[1]{\textcolor[rgb]{0.73,0.40,0.53}{\textbf{#1}}} -\newcommand\Cbe[1]{\textcolor[rgb]{0.67,0.13,1.00}{\textbf{#1}}} -\newcommand\CaS[1]{\textcolor[rgb]{0.82,0.25,0.23}{\textbf{#1}}} -\newcommand\CaR[1]{\textcolor[rgb]{0.50,0.00,0.50}{\textbf{#1}}} -\newcommand\CaQ[1]{\textcolor[rgb]{0.00,0.53,0.00}{\textit{#1}}} -\newcommand\CaP[1]{\textcolor[rgb]{0.72,0.53,0.04}{#1}} -\newcommand\CaW[1]{\textcolor[rgb]{0.73,0.27,0.27}{#1}} -\newcommand\CaV[1]{\textcolor[rgb]{0.67,0.13,1.00}{#1}} -\newcommand\CaU[1]{\textcolor[rgb]{0.73,0.27,0.27}{#1}} -\newcommand\CaT[1]{\textcolor[rgb]{0.00,0.00,1.00}{\textbf{#1}}} -\newcommand\CaK[1]{\textcolor[rgb]{0.00,0.53,0.00}{#1}} -\newcommand\CaJ[1]{\textcolor[rgb]{0.67,0.13,1.00}{#1}} -\newcommand\CaI[1]{\textcolor[rgb]{0.00,0.63,0.00}{#1}} -\newcommand\CaH[1]{\textcolor[rgb]{0.73,0.27,0.27}{#1}} -\newcommand\CaO[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} -\newcommand\CaN[1]{\textcolor[rgb]{0.73,0.27,0.27}{#1}} -\newcommand\CaM[1]{\textcolor[rgb]{0.00,0.00,0.50}{\textbf{#1}}} -\newcommand\CaL[1]{\textcolor[rgb]{0.00,0.00,1.00}{#1}} -\newcommand\CaC[1]{\textcolor[rgb]{0.63,0.00,0.00}{#1}} -\newcommand\CaB[1]{\textcolor[rgb]{0.00,0.53,0.00}{\textit{#1}}} -\newcommand\CaA[1]{\textcolor[rgb]{0.67,0.13,1.00}{#1}} -\newcommand\CaG[1]{\textcolor[rgb]{0.67,0.13,1.00}{\textbf{#1}}} -\newcommand\CaF[1]{\fcolorbox[rgb]{1.00,0.00,0.00}{1,1,1}{#1}} -\newcommand\CaE[1]{\textcolor[rgb]{0.72,0.53,0.04}{#1}} -\newcommand\CaD[1]{\textcolor[rgb]{1.00,0.00,0.00}{#1}} +\newcommand\PYba[1]{\textcolor[rgb]{0.67,0.13,1.00}{\textbf{#1}}} +\newcommand\PYaz[1]{\textcolor[rgb]{0.00,0.25,0.82}{#1}} +\newcommand\PYay[1]{\textcolor[rgb]{0.67,0.13,1.00}{#1}} +\newcommand\PYax[1]{\textcolor[rgb]{0.00,0.63,0.00}{#1}} +\newcommand\PYbc[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} +\newcommand\PYas[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} +\newcommand\PYar[1]{\textcolor[rgb]{0.72,0.53,0.04}{#1}} +\newcommand\PYaq[1]{\textcolor[rgb]{0.73,0.27,0.27}{\textit{#1}}} +\newcommand\PYap[1]{\textcolor[rgb]{0.72,0.53,0.04}{#1}} +\newcommand\PYaw[1]{\textcolor[rgb]{0.67,0.13,1.00}{\textbf{#1}}} +\newcommand\PYav[1]{\textcolor[rgb]{0.60,0.60,0.60}{\textbf{#1}}} +\newcommand\PYau[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} +\newcommand\PYat[1]{\textcolor[rgb]{0.67,0.13,1.00}{\textbf{#1}}} +\newcommand\PYak[1]{\textbf{#1}} +\newcommand\PYaj[1]{\textcolor[rgb]{0.73,0.40,0.53}{#1}} +\newcommand\PYai[1]{\textcolor[rgb]{0.72,0.53,0.04}{#1}} +\newcommand\PYah[1]{\textcolor[rgb]{0.63,0.63,0.00}{#1}} +\newcommand\PYao[1]{\textcolor[rgb]{0.53,0.00,0.00}{#1}} +\newcommand\PYan[1]{\textcolor[rgb]{0.00,0.50,0.00}{#1}} +\newcommand\PYam[1]{\textcolor[rgb]{0.73,0.40,0.13}{\textbf{#1}}} +\newcommand\PYal[1]{\textcolor[rgb]{0.67,0.13,1.00}{\textbf{#1}}} +\newcommand\PYac[1]{\textcolor[rgb]{0.73,0.27,0.27}{#1}} +\newcommand\PYab[1]{\textit{#1}} +\newcommand\PYaa[1]{\textcolor[rgb]{0.50,0.50,0.50}{#1}} +\newcommand\PYag[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} +\newcommand\PYaf[1]{\textcolor[rgb]{0.00,0.53,0.00}{\textit{#1}}} +\newcommand\PYae[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} +\newcommand\PYad[1]{\textcolor[rgb]{0.73,0.27,0.27}{#1}} +\newcommand\PYbb[1]{\textcolor[rgb]{0.73,0.27,0.27}{#1}} +\newcommand\PYaZ[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} +\newcommand\PYaY[1]{\textcolor[rgb]{0.00,0.00,0.50}{\textbf{#1}}} +\newcommand\PYaX[1]{\textcolor[rgb]{0.00,0.50,0.00}{\textbf{#1}}} +\newcommand\PYbd[1]{\textcolor[rgb]{0.73,0.40,0.53}{\textbf{#1}}} +\newcommand\PYbe[1]{\textcolor[rgb]{0.67,0.13,1.00}{\textbf{#1}}} +\newcommand\PYaS[1]{\textcolor[rgb]{0.82,0.25,0.23}{\textbf{#1}}} +\newcommand\PYaR[1]{\textcolor[rgb]{0.50,0.00,0.50}{\textbf{#1}}} +\newcommand\PYaQ[1]{\textcolor[rgb]{0.00,0.53,0.00}{\textit{#1}}} +\newcommand\PYaP[1]{\textcolor[rgb]{0.72,0.53,0.04}{#1}} +\newcommand\PYaW[1]{\textcolor[rgb]{0.73,0.27,0.27}{#1}} +\newcommand\PYaV[1]{\textcolor[rgb]{0.67,0.13,1.00}{#1}} +\newcommand\PYaU[1]{\textcolor[rgb]{0.73,0.27,0.27}{#1}} +\newcommand\PYaT[1]{\textcolor[rgb]{0.00,0.00,1.00}{\textbf{#1}}} +\newcommand\PYaK[1]{\textcolor[rgb]{0.00,0.53,0.00}{#1}} +\newcommand\PYaJ[1]{\textcolor[rgb]{0.67,0.13,1.00}{#1}} +\newcommand\PYaI[1]{\textcolor[rgb]{0.00,0.63,0.00}{#1}} +\newcommand\PYaH[1]{\textcolor[rgb]{0.73,0.27,0.27}{#1}} +\newcommand\PYaO[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} +\newcommand\PYaN[1]{\textcolor[rgb]{0.73,0.27,0.27}{#1}} +\newcommand\PYaM[1]{\textcolor[rgb]{0.00,0.00,0.50}{\textbf{#1}}} +\newcommand\PYaL[1]{\textcolor[rgb]{0.00,0.00,1.00}{#1}} +\newcommand\PYaC[1]{\textcolor[rgb]{0.63,0.00,0.00}{#1}} +\newcommand\PYaB[1]{\textcolor[rgb]{0.00,0.53,0.00}{\textit{#1}}} +\newcommand\PYaA[1]{\textcolor[rgb]{0.67,0.13,1.00}{#1}} +\newcommand\PYaG[1]{\textcolor[rgb]{0.67,0.13,1.00}{\textbf{#1}}} +\newcommand\PYaF[1]{\fcolorbox[rgb]{1.00,0.00,0.00}{1,1,1}{#1}} +\newcommand\PYaE[1]{\textcolor[rgb]{0.72,0.53,0.04}{#1}} +\newcommand\PYaD[1]{\textcolor[rgb]{1.00,0.00,0.00}{#1}} diff --git a/sandbox/code-block-directive/data/pygments-docutilsroles.sty b/sandbox/code-block-directive/data/pygments-docutilsroles.sty new file mode 100644 index 000000000..7abdf4931 --- /dev/null +++ b/sandbox/code-block-directive/data/pygments-docutilsroles.sty @@ -0,0 +1,55 @@ +% Stylesheet for pygments enhanced reStructured Text +% ================================================== +% +% :Author: Günter Milde +% :Contact: milde@users.berlios.de +% :Revision: $Revision: 5534 $ +% :Date: $Date: 2005-06-28$ +% :Copyright: © 2007, 2009 G. Milde, +% Released without warranties or conditions of any kind +% under the terms of the Apache License, Version 2.0 +% http://www.apache.org/licenses/LICENSE-2.0 +% +% This example style sheet provides syntax highlight for documents generated +% with the `rst2latex-highlight` pygments-enhanced Docutils front end. +% +% +% Separate paragraphs by vertical space +% ------------------------------------- +% +% This is not required for syntax highlight, but usually a good idea for +% documents with lots of source code. +% :: + +\usepackage{parskip} + +% Highlight code blocks +% --------------------- +% +% Pygments_ has an option to generate stylesheets for HTML and LaTeX. +% However, the "kryptic" codes used for HTML and LaTeX differ, so that +% the output of the command +% `pygmentize -S default -f latex -O commandprefix=docutilsrole` +% fails to work with rst2latex-highlight. +% :: + +% Colours with LaTeX +\usepackage{color} + +% Courier monotype fonts with bold and italic variants +\usepackage{courier} + +% keyword +\newcommand\docutilsrolek[1]{\textcolor[rgb]{0.67,0.13,1.00}{\textbf{#1}}} +% new function +\newcommand\docutilsrolenf[1]{\textcolor[rgb]{0.00,0.25,0.82}{#1}} +% punktuation +\newcommand\docutilsrolep[1]{\textcolor[rgb]{0.72,0.53,0.04}{#1}} +% string +\newcommand\docutilsroles[1]{\textcolor[rgb]{0.40,0.40,0.40}{\textit{#1}}} +% number +\newcommand\docutilsrolemf[1]{\textcolor[rgb]{0.00,0.53,0.00}{#1}} +% operator +\newcommand\docutilsrolear[1]{\textcolor[rgb]{0.72,0.53,0.04}{#1}} + +% Incomplete! diff --git a/sandbox/code-block-directive/docs/myfunction.py.htm b/sandbox/code-block-directive/docs/myfunction.py.htm index edc700246..62f7ae00f 100644 --- a/sandbox/code-block-directive/docs/myfunction.py.htm +++ b/sandbox/code-block-directive/docs/myfunction.py.htm @@ -1,29 +1,126 @@ -<?xml version="1.0" encoding="iso-8859-1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> -<meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" /> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" /> <title></title> -<link rel="stylesheet" href="../data/pygments-default.css" type="text/css" /> +<style type="text/css"> + +/* Stylesheet for pygments enhanced reStructured Text */ +/* ================================================== */ + +/* :Author: Guenter Milde */ +/* :Copyright: 2007 G. Milde */ +/* This stylesheet is released under the GPL v. 2 or later */ + +/* This stylesheet provides syntax highlight for documents generated with a */ +/* pygments_ enhanced reStructured Text -> html converter. */ + +/* Import the default docutils style sheet */ +/* --------------------------------------- */ +/* :: */ + +@import url("/stylesheets/html4css1.css"); + +/* Indent the code block */ +/* --------------------- */ + +/* Content copied from the `html4css1.css` rule for literal blocks. */ +/* Selector adapted to the output of Pygments_. :: */ + +div.highlight { + margin-left: 2em ; + margin-right: 2em ; + background-color: #eeeeee + } + + +/* Colour code blocks */ +/* ------------------ */ + +/* Pygments_ has an option to generate stylesheets for html and latex. */ +/* The following code is generated with the command */ +/* `pygmentize -S default -f html > pygments-default.css`:: */ + +.c { color: #008800; font-style: italic } /* Comment */ +.err { border: 1px solid #FF0000 } /* Error */ +.k { color: #AA22FF; font-weight: bold } /* Keyword */ +.o { color: #666666 } /* Operator */ +.cm { color: #008800; font-style: italic } /* Comment.Multiline */ +.cp { color: #008800 } /* Comment.Preproc */ +.c1 { color: #008800; font-style: italic } /* Comment.Single */ +.gd { color: #A00000 } /* Generic.Deleted */ +.ge { font-style: italic } /* Generic.Emph */ +.gr { color: #FF0000 } /* Generic.Error */ +.gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.gi { color: #00A000 } /* Generic.Inserted */ +.go { color: #808080 } /* Generic.Output */ +.gp { color: #000080; font-weight: bold } /* Generic.Prompt */ +.gs { font-weight: bold } /* Generic.Strong */ +.gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.gt { color: #0040D0 } /* Generic.Traceback */ +.kc { color: #AA22FF; font-weight: bold } /* Keyword.Constant */ +.kd { color: #AA22FF; font-weight: bold } /* Keyword.Declaration */ +.kp { color: #AA22FF } /* Keyword.Pseudo */ +.kr { color: #AA22FF; font-weight: bold } /* Keyword.Reserved */ +.kt { color: #AA22FF; font-weight: bold } /* Keyword.Type */ +.m { color: #666666 } /* Literal.Number */ +.s { color: #BB4444 } /* Literal.String */ +.na { color: #BB4444 } /* Name.Attribute */ +.nb { color: #AA22FF } /* Name.Builtin */ +.nc { color: #0000FF } /* Name.Class */ +.no { color: #880000 } /* Name.Constant */ +.nd { color: #AA22FF } /* Name.Decorator */ +.ni { color: #999999; font-weight: bold } /* Name.Entity */ +.ne { color: #D2413A; font-weight: bold } /* Name.Exception */ +.nf { color: #00A000 } /* Name.Function */ +.nl { color: #A0A000 } /* Name.Label */ +.nn { color: #0000FF; font-weight: bold } /* Name.Namespace */ +.nt { color: #008000; font-weight: bold } /* Name.Tag */ +.nv { color: #B8860B } /* Name.Variable */ +.ow { color: #AA22FF; font-weight: bold } /* Operator.Word */ +.mf { color: #666666 } /* Literal.Number.Float */ +.mh { color: #666666 } /* Literal.Number.Hex */ +.mi { color: #666666 } /* Literal.Number.Integer */ +.mo { color: #666666 } /* Literal.Number.Oct */ +.sb { color: #BB4444 } /* Literal.String.Backtick */ +.sc { color: #BB4444 } /* Literal.String.Char */ +.sd { color: #BB4444; font-style: italic } /* Literal.String.Doc */ +.s2 { color: #BB4444 } /* Literal.String.Double */ +.se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */ +.sh { color: #BB4444 } /* Literal.String.Heredoc */ +.si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */ +.sx { color: #008000 } /* Literal.String.Other */ +.sr { color: #BB6688 } /* Literal.String.Regex */ +.s1 { color: #BB4444 } /* Literal.String.Single */ +.ss { color: #B8860B } /* Literal.String.Symbol */ +.bp { color: #AA22FF } /* Name.Builtin.Pseudo */ +.vc { color: #B8860B } /* Name.Variable.Class */ +.vg { color: #B8860B } /* Name.Variable.Global */ +.vi { color: #B8860B } /* Name.Variable.Instance */ +.il { color: #666666 } /* Literal.Number.Integer.Long */ + +/* .. _pygments: http://pygments.org/ */ + +</style> </head> <body> <div class="document"> + + <p>This is a test of the new code-block directive:</p> <!-- Translate this document to HTML with a pygments enhanced frontend, e.g. -rst2html-highlight - -stylesheet=pygments-default.css - -link-stylesheet --> +../rst2html-highlight - -stylesheet=../data/pygments-default.css + +../rst2latex-highlight - -stylesheet=../data/pygments-docutileroles.sty --> <pre class="code-block python literal-block"> <span class="k">def</span> <span class="nf">my_function</span><span class="p">():</span> <span class="s">"just a test"</span> - <span class="k">print</span> <span class="mi">8</span><span class="o">/</span><span class="mi">2</span> + <span class="k">print</span> <span class="mf">8</span><span class="o">/</span><span class="mf">2</span> </pre> </div> -<div class="footer"> -<hr class="footer" /> -Generated on: 2007-06-05. - -</div> </body> </html> diff --git a/sandbox/code-block-directive/docs/myfunction.py.newlatex2e.pdf b/sandbox/code-block-directive/docs/myfunction.py.newlatex2e.pdf Binary files differdeleted file mode 100644 index 658eb59d7..000000000 --- a/sandbox/code-block-directive/docs/myfunction.py.newlatex2e.pdf +++ /dev/null diff --git a/sandbox/code-block-directive/docs/myfunction.py.newlatex2e.tex b/sandbox/code-block-directive/docs/myfunction.py.newlatex2e.tex deleted file mode 100644 index d2d67cfea..000000000 --- a/sandbox/code-block-directive/docs/myfunction.py.newlatex2e.tex +++ /dev/null @@ -1,209 +0,0 @@ -% Generated by Docutils 0.4.1 <http://docutils.sourceforge.net>. - -% Docutils settings: -\providecommand{\Dlanguageiso}{en} -\providecommand{\Dlanguagebabel}{english} - -% Docutils stylesheet: -\input{/usr/lib/python2.4/site-packages/docutils/writers/newlatex2e/base.tex} - -% Default definitions for Docutils nodes: -\providecommand{\DNText}[1]{#1} -\providecommand{\DNabbreviation}[1]{#1} -\providecommand{\DNacronym}[1]{#1} -\providecommand{\DNaddress}[1]{#1} -\providecommand{\DNadmonition}[1]{#1} -\providecommand{\DNattention}[1]{#1} -\providecommand{\DNattribution}[1]{#1} -\providecommand{\DNauthor}[1]{#1} -\providecommand{\DNauthors}[1]{#1} -\providecommand{\DNblockquote}[1]{#1} -\providecommand{\DNbulletlist}[1]{#1} -\providecommand{\DNcaption}[1]{#1} -\providecommand{\DNcaution}[1]{#1} -\providecommand{\DNcitation}[1]{#1} -\providecommand{\DNcitationreference}[1]{#1} -\providecommand{\DNclassifier}[1]{#1} -\providecommand{\DNcolspec}[1]{#1} -\providecommand{\DNcomment}[1]{#1} -\providecommand{\DNcompound}[1]{#1} -\providecommand{\DNcontact}[1]{#1} -\providecommand{\DNcontainer}[1]{#1} -\providecommand{\DNcopyright}[1]{#1} -\providecommand{\DNdanger}[1]{#1} -\providecommand{\DNdate}[1]{#1} -\providecommand{\DNdecoration}[1]{#1} -\providecommand{\DNdefinition}[1]{#1} -\providecommand{\DNdefinitionlist}[1]{#1} -\providecommand{\DNdefinitionlistitem}[1]{#1} -\providecommand{\DNdescription}[1]{#1} -\providecommand{\DNdocinfo}[1]{#1} -\providecommand{\DNdoctestblock}[1]{#1} -\providecommand{\DNdocument}[1]{#1} -\providecommand{\DNemphasis}[1]{#1} -\providecommand{\DNentry}[1]{#1} -\providecommand{\DNenumeratedlist}[1]{#1} -\providecommand{\DNerror}[1]{#1} -\providecommand{\DNfield}[1]{#1} -\providecommand{\DNfieldbody}[1]{#1} -\providecommand{\DNfieldlist}[1]{#1} -\providecommand{\DNfieldname}[1]{#1} -\providecommand{\DNfigure}[1]{#1} -\providecommand{\DNfooter}[1]{#1} -\providecommand{\DNfootnote}[1]{#1} -\providecommand{\DNfootnotereference}[1]{#1} -\providecommand{\DNgenerated}[1]{#1} -\providecommand{\DNheader}[1]{#1} -\providecommand{\DNhint}[1]{#1} -\providecommand{\DNimage}[1]{#1} -\providecommand{\DNimportant}[1]{#1} -\providecommand{\DNinline}[1]{#1} -\providecommand{\DNlabel}[1]{#1} -\providecommand{\DNlegend}[1]{#1} -\providecommand{\DNline}[1]{#1} -\providecommand{\DNlineblock}[1]{#1} -\providecommand{\DNlistitem}[1]{#1} -\providecommand{\DNliteral}[1]{#1} -\providecommand{\DNliteralblock}[1]{#1} -\providecommand{\DNnote}[1]{#1} -\providecommand{\DNoption}[1]{#1} -\providecommand{\DNoptionargument}[1]{#1} -\providecommand{\DNoptiongroup}[1]{#1} -\providecommand{\DNoptionlist}[1]{#1} -\providecommand{\DNoptionlistitem}[1]{#1} -\providecommand{\DNoptionstring}[1]{#1} -\providecommand{\DNorganization}[1]{#1} -\providecommand{\DNparagraph}[1]{#1} -\providecommand{\DNpending}[1]{#1} -\providecommand{\DNproblematic}[1]{#1} -\providecommand{\DNraw}[1]{#1} -\providecommand{\DNreference}[1]{#1} -\providecommand{\DNrevision}[1]{#1} -\providecommand{\DNrow}[1]{#1} -\providecommand{\DNrubric}[1]{#1} -\providecommand{\DNsection}[1]{#1} -\providecommand{\DNsidebar}[1]{#1} -\providecommand{\DNstatus}[1]{#1} -\providecommand{\DNstrong}[1]{#1} -\providecommand{\DNsubscript}[1]{#1} -\providecommand{\DNsubstitutiondefinition}[1]{#1} -\providecommand{\DNsubstitutionreference}[1]{#1} -\providecommand{\DNsubtitle}[1]{#1} -\providecommand{\DNsuperscript}[1]{#1} -\providecommand{\DNsystemmessage}[1]{#1} -\providecommand{\DNtable}[1]{#1} -\providecommand{\DNtarget}[1]{#1} -\providecommand{\DNtbody}[1]{#1} -\providecommand{\DNterm}[1]{#1} -\providecommand{\DNtgroup}[1]{#1} -\providecommand{\DNthead}[1]{#1} -\providecommand{\DNtip}[1]{#1} -\providecommand{\DNtitle}[1]{#1} -\providecommand{\DNtitlereference}[1]{#1} -\providecommand{\DNtopic}[1]{#1} -\providecommand{\DNtransition}[1]{#1} -\providecommand{\DNversion}[1]{#1} -\providecommand{\DNwarning}[1]{#1} - -% Auxiliary definitions: -\providecommand{\Dsetattr}[2]{} -\providecommand{\Dparent}{} % variable -\providecommand{\Dattr}[5]{#5} -\providecommand{\Dattrlen}{} % variable -\providecommand{\Dtitleastext}{x} % variable -\providecommand{\Dsinglebackref}{} % variable -\providecommand{\Dmultiplebackrefs}{} % variable -\providecommand{\Dparagraphindented}{false} % variable - - -\Dvisitdocument% - \Dattr{}{source}{/home/milde/.python/PyLit/trunk/rstdocs/features/myfunction.py.txt}{document}{% - }% - \renewcommand{\Dparent}{document}% - \DNdecoration{% - \renewcommand{\Dparent}{decoration}% - \DNfooter{% - \renewcommand{\Dparagraphindented}{false}% - \renewcommand{\Dparent}{footer}% - \DNparagraph{% - Generated{ }on:{ }2007{-}06{-}05.{ }% - }% - }% - }% - \renewcommand{\Dparagraphindented}{true}% - \renewcommand{\Dparent}{document}% - \DNparagraph{% - This{ }is{ }a{ }test{ }of{ }the{ }new{ }code{-}block{ }directive:% - }% - \Dauxiliaryspace% - \renewcommand{\Dparent}{document}% - \DNcomment{% - \Dattr{}{xml:space}{preserve}{comment}{% - % Translate this document to HTML with a pygments enhanced frontend, e.g. - % - % rst2html-highlight --stylesheet=pygments-default.css --link-stylesheet - }}% - \renewcommand{\Dparent}{document}% - \def\DcurrentNliteralblockAraw_content{[u'def my_function():', u' "{}just a test"{}', u' print 8/2']}% - \DNliteralblock{% - \renewcommand{\Dattrlen}{2}% - \Dattr{1}{classes}{code-block}{literalblock}{% - \Dattr{2}{classes}{python}{literalblock}{% - \Dattr{}{raw_content}{[u'def my_function():', u' "{}just a test"{}', u' print 8/2']}{literalblock}{% - \Dattr{}{xml:space}{preserve}{literalblock}{% - \renewcommand{\Dparent}{literalblock}% - \DNinline{% - \renewcommand{\Dattrlen}{1}% - \Dattr{1}{classes}{k}{inline}{% - def% - }}% - ~% - \renewcommand{\Dparent}{literalblock}% - \DNinline{% - \renewcommand{\Dattrlen}{1}% - \Dattr{1}{classes}{nf}{inline}{% - my{\Dtextunderscore}function% - }}% - \renewcommand{\Dparent}{literalblock}% - \DNinline{% - \renewcommand{\Dattrlen}{1}% - \Dattr{1}{classes}{p}{inline}{% - ():% - }}% - \mbox{}\\~~~~% - \renewcommand{\Dparent}{literalblock}% - \DNinline{% - \renewcommand{\Dattrlen}{1}% - \Dattr{1}{classes}{s}{inline}{% - {"}just~a~test{"}% - }}% - \mbox{}\\~~~~% - \renewcommand{\Dparent}{literalblock}% - \DNinline{% - \renewcommand{\Dattrlen}{1}% - \Dattr{1}{classes}{k}{inline}{% - print% - }}% - ~% - \renewcommand{\Dparent}{literalblock}% - \DNinline{% - \renewcommand{\Dattrlen}{1}% - \Dattr{1}{classes}{mi}{inline}{% - 8% - }}% - \renewcommand{\Dparent}{literalblock}% - \DNinline{% - \renewcommand{\Dattrlen}{1}% - \Dattr{1}{classes}{o}{inline}{% - /% - }}% - \renewcommand{\Dparent}{literalblock}% - \DNinline{% - \renewcommand{\Dattrlen}{1}% - \Dattr{1}{classes}{mi}{inline}{% - 2% - }}% - \mbox{}\\% - }}}}}% - \let\DcurrentNliteralblockAraw_content=\relax% -\Ddepartdocument% diff --git a/sandbox/code-block-directive/docs/myfunction.py.pdf b/sandbox/code-block-directive/docs/myfunction.py.pdf Binary files differnew file mode 100644 index 000000000..5b847ab6f --- /dev/null +++ b/sandbox/code-block-directive/docs/myfunction.py.pdf diff --git a/sandbox/code-block-directive/docs/myfunction.py.tex b/sandbox/code-block-directive/docs/myfunction.py.tex index 689a02703..6d5ddd5dd 100644 --- a/sandbox/code-block-directive/docs/myfunction.py.tex +++ b/sandbox/code-block-directive/docs/myfunction.py.tex @@ -56,7 +56,7 @@ \newcommand{\titlereference}[1]{\textsl{#1}} % end of "some commands" % user specified packages and stylesheets: -\usepackage{cmlgc} +\usepackage{../data/pygments-docutilsroles} \ifthenelse{\isundefined{\hypersetup}}{ \usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref} }{} @@ -80,7 +80,9 @@ This is a test of the new code-block directive: % Translate this document to HTML with a pygments enhanced frontend, e.g. % -% rst2html-highlight --stylesheet=pygments-default.css --link-stylesheet +% rst2html-highlight --stylesheet=../data/pygments-default.css --link-stylesheet +% +% rst2latex-highlight --stylesheet=../data/pygments-docutileroles.sty \begin{quote}{\ttfamily \raggedright \noindent \DUrole{k}{def}~\DUrole{nf}{my{\_}function}\DUrole{p}{():}~\\ ~~~~\DUrole{s}{"just~a~test"}~\\ diff --git a/sandbox/code-block-directive/docs/myfunction.py.txt b/sandbox/code-block-directive/docs/myfunction.py.txt index 926733dc0..783e5b0b6 100644 --- a/sandbox/code-block-directive/docs/myfunction.py.txt +++ b/sandbox/code-block-directive/docs/myfunction.py.txt @@ -2,7 +2,9 @@ This is a test of the new code-block directive: .. Translate this document to HTML with a pygments enhanced frontend, e.g. - rst2html-highlight --stylesheet=pygments-default.css --link-stylesheet + ../rst2html-highlight --stylesheet=../data/pygments-default.css + + ../rst2latex-highlight --stylesheet=../data/pygments-docutileroles.sty .. code-block:: python diff --git a/sandbox/code-block-directive/docs/pygments_code_block_directive-bunt.py.htm b/sandbox/code-block-directive/docs/pygments_code_block_directive-bunt.py.htm deleted file mode 100644 index 78bb809e9..000000000 --- a/sandbox/code-block-directive/docs/pygments_code_block_directive-bunt.py.htm +++ /dev/null @@ -1,314 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1" ?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> -<meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" /> -<title></title> -<meta name="author" content="a Pygments author|contributor; Felix Wiemann; Guenter Milde" /> -<meta name="date" content="2007-06-08" /> -<meta name="copyright" content="This module has been placed in the public domain." /> -<style type="text/css"> - -/* Stylesheet for pygments enhanced reStructured Text */ -/* ================================================== */ - -/* :Author: Guenter Milde */ -/* :Copyright: 2007 G. Milde */ -/* This stylesheet is released under the GPL v. 2 or later */ - -/* This stylesheet provides syntax highlight for documents generated with a */ -/* pygments_ enhanced reStructured Text -> html converter. */ - -/* Import the default docutils style sheet */ -/* --------------------------------------- */ -/* :: */ - -@import url("/stylesheets/html4css1.css"); - -/* Indent the code block */ -/* --------------------- */ - -/* Content copied from the `html4css1.css` rule for literal blocks. */ -/* Selector adapted to the output of Pygments_. :: */ - -div.highlight { - margin-left: 2em ; - margin-right: 2em ; - background-color: #eeeeee - } - - -/* Colour code blocks */ -/* ------------------ */ - -/* Pygments_ has an option to generate stylesheets for html and latex. */ -/* The following code is generated with the command */ -/* `pygmentize -S default -f html > pygments-default.css`:: */ - -.c { color: #008800; font-style: italic } /* Comment */ -.err { border: 1px solid #FF0000 } /* Error */ -.k { color: #AA22FF; font-weight: bold } /* Keyword */ -.o { color: #666666 } /* Operator */ -.cm { color: #008800; font-style: italic } /* Comment.Multiline */ -.cp { color: #008800 } /* Comment.Preproc */ -.c1 { color: #008800; font-style: italic } /* Comment.Single */ -.gd { color: #A00000 } /* Generic.Deleted */ -.ge { font-style: italic } /* Generic.Emph */ -.gr { color: #FF0000 } /* Generic.Error */ -.gh { color: #000080; font-weight: bold } /* Generic.Heading */ -.gi { color: #00A000 } /* Generic.Inserted */ -.go { color: #808080 } /* Generic.Output */ -.gp { color: #000080; font-weight: bold } /* Generic.Prompt */ -.gs { font-weight: bold } /* Generic.Strong */ -.gu { color: #800080; font-weight: bold } /* Generic.Subheading */ -.gt { color: #0040D0 } /* Generic.Traceback */ -.kc { color: #AA22FF; font-weight: bold } /* Keyword.Constant */ -.kd { color: #AA22FF; font-weight: bold } /* Keyword.Declaration */ -.kp { color: #AA22FF } /* Keyword.Pseudo */ -.kr { color: #AA22FF; font-weight: bold } /* Keyword.Reserved */ -.kt { color: #AA22FF; font-weight: bold } /* Keyword.Type */ -.m { color: #666666 } /* Literal.Number */ -.s { color: #BB4444 } /* Literal.String */ -.na { color: #BB4444 } /* Name.Attribute */ -.nb { color: #AA22FF } /* Name.Builtin */ -.nc { color: #0000FF } /* Name.Class */ -.no { color: #880000 } /* Name.Constant */ -.nd { color: #AA22FF } /* Name.Decorator */ -.ni { color: #999999; font-weight: bold } /* Name.Entity */ -.ne { color: #D2413A; font-weight: bold } /* Name.Exception */ -.nf { color: #00A000 } /* Name.Function */ -.nl { color: #A0A000 } /* Name.Label */ -.nn { color: #0000FF; font-weight: bold } /* Name.Namespace */ -.nt { color: #008000; font-weight: bold } /* Name.Tag */ -.nv { color: #B8860B } /* Name.Variable */ -.ow { color: #AA22FF; font-weight: bold } /* Operator.Word */ -.mf { color: #666666 } /* Literal.Number.Float */ -.mh { color: #666666 } /* Literal.Number.Hex */ -.mi { color: #666666 } /* Literal.Number.Integer */ -.mo { color: #666666 } /* Literal.Number.Oct */ -.sb { color: #BB4444 } /* Literal.String.Backtick */ -.sc { color: #BB4444 } /* Literal.String.Char */ -.sd { color: #BB4444; font-style: italic } /* Literal.String.Doc */ -.s2 { color: #BB4444 } /* Literal.String.Double */ -.se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */ -.sh { color: #BB4444 } /* Literal.String.Heredoc */ -.si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */ -.sx { color: #008000 } /* Literal.String.Other */ -.sr { color: #BB6688 } /* Literal.String.Regex */ -.s1 { color: #BB4444 } /* Literal.String.Single */ -.ss { color: #B8860B } /* Literal.String.Symbol */ -.bp { color: #AA22FF } /* Name.Builtin.Pseudo */ -.vc { color: #B8860B } /* Name.Variable.Class */ -.vg { color: #B8860B } /* Name.Variable.Global */ -.vi { color: #B8860B } /* Name.Variable.Instance */ -.il { color: #666666 } /* Literal.Number.Integer.Long */ - -/* .. _pygments: http://pygments.org/ */ - -</style> -</head> -<body> -<div class="document"> -<table class="docinfo" frame="void" rules="none"> -<col class="docinfo-name" /> -<col class="docinfo-content" /> -<tbody valign="top"> -<tr><th class="docinfo-name">Author:</th> -<td>a Pygments author|contributor; Felix Wiemann; Guenter Milde</td></tr> -<tr><th class="docinfo-name">Date:</th> -<td>2007-06-08</td></tr> -<tr><th class="docinfo-name">Copyright:</th> -<td>This module has been placed in the public domain.</td></tr> -</tbody> -</table> -<!-- #!/usr/bin/python --> -<p>This is a merge of <a class="reference" href="http://pygments.org/docs/rstdirective/">Using Pygments in ReST documents</a> from the <a class="reference" href="http://pygments.org/">pygments</a> -documentation, and a <a class="reference" href="http://article.gmane.org/gmane.text.docutils.user/3689">proof of concept</a> by Felix Wiemann.</p> -<table border="1" class="docutils"> -<colgroup> -<col width="14%" /> -<col width="86%" /> -</colgroup> -<tbody valign="top"> -<tr><td>2007-06-01</td> -<td>Removed redundancy from class values.</td> -</tr> -<tr><td>2007-06-04</td> -<td>Merge of successive tokens of same type -(code taken from pygments.formatters.others).</td> -</tr> -<tr><td>2007-06-05</td> -<td>Separate docutils formatter script -Use pygments' CSS class names (like the html formatter) -allowing the use of pygments-produced style sheets.</td> -</tr> -<tr><td>2007-06-07</td> -<td>Merge in the formatting of the parsed tokens -(misnamed as docutils_formatter) as class DocutilsInterface</td> -</tr> -<tr><td>2007-06-08</td> -<td>Failsave implementation (fallback to a standard literal block -if pygments not found)</td> -</tr> -</tbody> -</table> -<!-- to get the syntax highlight in the html output of this file, convert with:: - -./rst2html-highlight - -stylesheet=data/pygments-default.css --> -<pre class="code-block python literal-block"> -<span class="sd">"""Define and register a code-block directive using pygments -"""</span> - -</pre> -<div class="section"> -<h1><a id="requirements" name="requirements">Requirements</a></h1> -<pre class="code-block python literal-block"> -<span class="k">from</span> <span class="nn">docutils</span> <span class="k">import</span> <span class="n">nodes</span> -<span class="k">from</span> <span class="nn">docutils.parsers.rst</span> <span class="k">import</span> <span class="n">directives</span> -<span class="k">try</span><span class="p">:</span> - <span class="k">import</span> <span class="nn">pygments</span> - <span class="k">from</span> <span class="nn">pygments.lexers</span> <span class="k">import</span> <span class="n">get_lexer_by_name</span> - <span class="k">from</span> <span class="nn">pygments.formatters.html</span> <span class="k">import</span> <span class="n">_get_ttype_class</span> -<span class="k">except</span> <span class="ne">ImportError</span><span class="p">:</span> - <span class="k">pass</span> - -</pre> -</div> -<div class="section"> -<h1><a id="customisation" name="customisation">Customisation</a></h1> -<p>Do not insert inline nodes for the following tokens. -(You could add e.g. Token.Punctuation like <tt class="docutils literal"><span class="pre">['',</span> <span class="pre">'p']</span></tt>.)</p> -<pre class="code-block python literal-block"> -<span class="n">unstyled_tokens</span> <span class="o">=</span> <span class="p">[</span><span class="s">''</span><span class="p">]</span> - -</pre> -</div> -<div class="section"> -<h1><a id="docutilsinterface" name="docutilsinterface">DocutilsInterface</a></h1> -<p>This interface class combines code from -pygments.formatters.html and pygments.formatters.others.</p> -<p>It does not require anything of docutils and could also become a part of -pygments</p> -<pre class="code-block python literal-block"> -<span class="k">class</span> <span class="nc">DocutilsInterface</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span> - <span class="sd">"""Parse `code` string and yield "classified" tokens. - - Arguments - - code -- string of source code to parse - language -- formal language the code is written in. - - Merge subsequent tokens of the same token-type. - - Yields the tokens as ``(ttype_class, value)`` tuples, - where ttype_class is taken from pygments.token.STANDARD_TYPES and - corresponds to the class argument used in pygments html output. - - """</span> - - <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">code</span><span class="p">,</span> <span class="n">language</span><span class="p">):</span> - <span class="bp">self</span><span class="o">.</span><span class="n">code</span> <span class="o">=</span> <span class="n">code</span> - <span class="bp">self</span><span class="o">.</span><span class="n">language</span> <span class="o">=</span> <span class="n">language</span> - - <span class="k">def</span> <span class="nf">lex</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> - <span class="c"># Get lexer for language (use text as fallback)</span> - <span class="k">try</span><span class="p">:</span> - <span class="n">lexer</span> <span class="o">=</span> <span class="n">get_lexer_by_name</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">language</span><span class="p">)</span> - <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span> - <span class="c"># info: "no pygments lexer for %s, using 'text'"%self.language</span> - <span class="n">lexer</span> <span class="o">=</span> <span class="n">get_lexer_by_name</span><span class="p">(</span><span class="s">'text'</span><span class="p">)</span> - <span class="k">return</span> <span class="n">pygments</span><span class="o">.</span><span class="n">lex</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">code</span><span class="p">,</span> <span class="n">lexer</span><span class="p">)</span> - - - <span class="k">def</span> <span class="nf">join</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">tokens</span><span class="p">):</span> - <span class="sd">"""join subsequent tokens of same token-type - """</span> - <span class="n">tokens</span> <span class="o">=</span> <span class="nb">iter</span><span class="p">(</span><span class="n">tokens</span><span class="p">)</span> - <span class="p">(</span><span class="n">lasttype</span><span class="p">,</span> <span class="n">lastval</span><span class="p">)</span> <span class="o">=</span> <span class="n">tokens</span><span class="o">.</span><span class="n">next</span><span class="p">()</span> - <span class="k">for</span> <span class="n">ttype</span><span class="p">,</span> <span class="n">value</span> <span class="ow">in</span> <span class="n">tokens</span><span class="p">:</span> - <span class="k">if</span> <span class="n">ttype</span> <span class="ow">is</span> <span class="n">lasttype</span><span class="p">:</span> - <span class="n">lastval</span> <span class="o">+=</span> <span class="n">value</span> - <span class="k">else</span><span class="p">:</span> - <span class="k">yield</span><span class="p">(</span><span class="n">lasttype</span><span class="p">,</span> <span class="n">lastval</span><span class="p">)</span> - <span class="p">(</span><span class="n">lasttype</span><span class="p">,</span> <span class="n">lastval</span><span class="p">)</span> <span class="o">=</span> <span class="p">(</span><span class="n">ttype</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span> - <span class="k">yield</span><span class="p">(</span><span class="n">lasttype</span><span class="p">,</span> <span class="n">lastval</span><span class="p">)</span> - - <span class="k">def</span> <span class="nf">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> - <span class="sd">"""parse code string and yield "clasified" tokens - """</span> - <span class="k">try</span><span class="p">:</span> - <span class="n">tokens</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">lex</span><span class="p">()</span> - <span class="k">except</span> <span class="ne">IOError</span><span class="p">:</span> - <span class="k">print</span> <span class="s">"INFO: Pygments lexer not found, using fallback"</span> - <span class="c"># TODO: write message to INFO</span> - <span class="k">yield</span> <span class="p">(</span><span class="s">''</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">code</span><span class="p">)</span> - <span class="k">return</span> - - <span class="k">for</span> <span class="n">ttype</span><span class="p">,</span> <span class="n">value</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">tokens</span><span class="p">):</span> - <span class="k">yield</span> <span class="p">(</span><span class="n">_get_ttype_class</span><span class="p">(</span><span class="n">ttype</span><span class="p">),</span> <span class="n">value</span><span class="p">)</span> - -</pre> -</div> -<div class="section"> -<h1><a id="code-block-directive" name="code-block-directive">code_block_directive</a></h1> -<pre class="code-block python literal-block"> -<span class="k">def</span> <span class="nf">code_block_directive</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">arguments</span><span class="p">,</span> <span class="n">options</span><span class="p">,</span> <span class="n">content</span><span class="p">,</span> <span class="n">lineno</span><span class="p">,</span> - <span class="n">content_offset</span><span class="p">,</span> <span class="n">block_text</span><span class="p">,</span> <span class="n">state</span><span class="p">,</span> <span class="n">state_machine</span><span class="p">):</span> - <span class="sd">"""parse and classify content of a code_block - """</span> - <span class="n">language</span> <span class="o">=</span> <span class="n">arguments</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> - <span class="c"># create a literal block element and set class argument</span> - <span class="n">code_block</span> <span class="o">=</span> <span class="n">nodes</span><span class="o">.</span><span class="n">literal_block</span><span class="p">(</span><span class="n">classes</span><span class="o">=</span><span class="p">[</span><span class="s">"code-block"</span><span class="p">,</span> <span class="n">language</span><span class="p">])</span> - - <span class="c"># parse content with pygments and add to code_block element</span> - <span class="k">for</span> <span class="n">cls</span><span class="p">,</span> <span class="n">value</span> <span class="ow">in</span> <span class="n">DocutilsInterface</span><span class="p">(</span><span class="n">u</span><span class="s">'</span><span class="se">\n</span><span class="s">'</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">content</span><span class="p">),</span> <span class="n">language</span><span class="p">):</span> - <span class="k">if</span> <span class="n">cls</span> <span class="ow">in</span> <span class="n">unstyled_tokens</span><span class="p">:</span> - <span class="c"># insert as Text to decrease the verbosity of the output.</span> - <span class="n">code_block</span> <span class="o">+=</span> <span class="n">nodes</span><span class="o">.</span><span class="n">Text</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span> - <span class="k">else</span><span class="p">:</span> - <span class="n">code_block</span> <span class="o">+=</span> <span class="n">nodes</span><span class="o">.</span><span class="n">inline</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">classes</span><span class="o">=</span><span class="p">[</span><span class="n">cls</span><span class="p">])</span> - - <span class="k">return</span> <span class="p">[</span><span class="n">code_block</span><span class="p">]</span> - -</pre> -</div> -<div class="section"> -<h1><a id="register-directive" name="register-directive">Register Directive</a></h1> -<pre class="code-block python literal-block"> -<span class="n">code_block_directive</span><span class="o">.</span><span class="n">arguments</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span> -<span class="n">code_block_directive</span><span class="o">.</span><span class="n">content</span> <span class="o">=</span> <span class="mi">1</span> -<span class="n">directives</span><span class="o">.</span><span class="n">register_directive</span><span class="p">(</span><span class="s">'code-block'</span><span class="p">,</span> <span class="n">code_block_directive</span><span class="p">)</span> - -</pre> -</div> -<div class="section"> -<h1><a id="test-output" name="test-output">Test output</a></h1> -<p>If called from the command line, call the docutils publisher to render the -input</p> -<pre class="code-block python literal-block"> -<span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s">'__main__'</span><span class="p">:</span> - <span class="k">from</span> <span class="nn">docutils.core</span> <span class="k">import</span> <span class="n">publish_cmdline</span><span class="p">,</span> <span class="n">default_description</span> - <span class="n">description</span> <span class="o">=</span> <span class="s">"code-block directive test output"</span> <span class="o">+</span> <span class="n">default_description</span> - <span class="k">try</span><span class="p">:</span> - <span class="k">import</span> <span class="nn">locale</span> - <span class="n">locale</span><span class="o">.</span><span class="n">setlocale</span><span class="p">(</span><span class="n">locale</span><span class="o">.</span><span class="n">LC_ALL</span><span class="p">,</span> <span class="s">''</span><span class="p">)</span> - <span class="k">except</span><span class="p">:</span> - <span class="k">pass</span> - <span class="c"># Uncomment the desired output format:</span> - <span class="n">publish_cmdline</span><span class="p">(</span><span class="n">writer_name</span><span class="o">=</span><span class="s">'pseudoxml'</span><span class="p">,</span> <span class="n">description</span><span class="o">=</span><span class="n">description</span><span class="p">)</span> - <span class="c"># publish_cmdline(writer_name='xml', description=description)</span> - <span class="c"># publish_cmdline(writer_name='html', description=description)</span> - <span class="c"># publish_cmdline(writer_name='latex', description=description)</span> - <span class="c"># publish_cmdline(writer_name='newlatex2e', description=description)</span> - -</pre> -</div> -</div> -<div class="footer"> -<hr class="footer" /> -Generated on: 2007-06-13. - -</div> -</body> -</html> diff --git a/sandbox/code-block-directive/docs/pygments_code_block_directive-bunt.py.txt b/sandbox/code-block-directive/docs/pygments_code_block_directive-bunt.py.txt deleted file mode 100644 index d7112e255..000000000 --- a/sandbox/code-block-directive/docs/pygments_code_block_directive-bunt.py.txt +++ /dev/null @@ -1,191 +0,0 @@ -.. #!/usr/bin/python - -:Author: a Pygments author|contributor; Felix Wiemann; Guenter Milde -:Date: $Date$ -:Copyright: This module has been placed in the public domain. - -This is a merge of `Using Pygments in ReST documents`_ from the pygments_ -documentation, and a `proof of concept`_ by Felix Wiemann. - -========== =========================================================== -2007-06-01 Removed redundancy from class values. -2007-06-04 Merge of successive tokens of same type - (code taken from pygments.formatters.others). -2007-06-05 Separate docutils formatter script - Use pygments' CSS class names (like the html formatter) - allowing the use of pygments-produced style sheets. -2007-06-07 Merge in the formatting of the parsed tokens - (misnamed as docutils_formatter) as class DocutilsInterface -2007-06-08 Failsave implementation (fallback to a standard literal block - if pygments not found) -========== =========================================================== - -.. to get the syntax highlight in the html output of this file, convert with:: - - ./rst2html-highlight --stylesheet=data/pygments-default.css - -.. code-block:: python - - """Define and register a code-block directive using pygments - """ - -Requirements ------------- - -.. code-block:: python - - from docutils import nodes - from docutils.parsers.rst import directives - try: - import pygments - from pygments.lexers import get_lexer_by_name - from pygments.formatters.html import _get_ttype_class - except ImportError: - pass - - - -Customisation -------------- - -Do not insert inline nodes for the following tokens. -(You could add e.g. Token.Punctuation like ``['', 'p']``.) - -.. code-block:: python - - unstyled_tokens = [''] - -DocutilsInterface ------------------ - -This interface class combines code from -pygments.formatters.html and pygments.formatters.others. - -It does not require anything of docutils and could also become a part of -pygments - -.. code-block:: python - - class DocutilsInterface(object): - """Parse `code` string and yield "classified" tokens. - - Arguments - - code -- string of source code to parse - language -- formal language the code is written in. - - Merge subsequent tokens of the same token-type. - - Yields the tokens as ``(ttype_class, value)`` tuples, - where ttype_class is taken from pygments.token.STANDARD_TYPES and - corresponds to the class argument used in pygments html output. - - """ - - def __init__(self, code, language): - self.code = code - self.language = language - - def lex(self): - # Get lexer for language (use text as fallback) - try: - lexer = get_lexer_by_name(self.language) - except ValueError: - # info: "no pygments lexer for %s, using 'text'"%self.language - lexer = get_lexer_by_name('text') - return pygments.lex(self.code, lexer) - - - def join(self, tokens): - """join subsequent tokens of same token-type - """ - tokens = iter(tokens) - (lasttype, lastval) = tokens.next() - for ttype, value in tokens: - if ttype is lasttype: - lastval += value - else: - yield(lasttype, lastval) - (lasttype, lastval) = (ttype, value) - yield(lasttype, lastval) - - def __iter__(self): - """parse code string and yield "clasified" tokens - """ - try: - tokens = self.lex() - except IOError: - print "INFO: Pygments lexer not found, using fallback" - # TODO: write message to INFO - yield ('', self.code) - return - - for ttype, value in self.join(tokens): - yield (_get_ttype_class(ttype), value) - - - -code_block_directive --------------------- - -.. code-block:: python - - def code_block_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - """parse and classify content of a code_block - """ - language = arguments[0] - # create a literal block element and set class argument - code_block = nodes.literal_block(classes=["code-block", language]) - - # parse content with pygments and add to code_block element - for cls, value in DocutilsInterface(u'\n'.join(content), language): - if cls in unstyled_tokens: - # insert as Text to decrease the verbosity of the output. - code_block += nodes.Text(value, value) - else: - code_block += nodes.inline(value, value, classes=[cls]) - - return [code_block] - - -Register Directive ------------------- - -.. code-block:: python - - code_block_directive.arguments = (1, 0, 1) - code_block_directive.content = 1 - directives.register_directive('code-block', code_block_directive) - -.. _doctutils: http://docutils.sf.net/ -.. _pygments: http://pygments.org/ -.. _Using Pygments in ReST documents: http://pygments.org/docs/rstdirective/ -.. _proof of concept: - http://article.gmane.org/gmane.text.docutils.user/3689 - -Test output ------------ - -If called from the command line, call the docutils publisher to render the -input - -.. code-block:: python - - if __name__ == '__main__': - from docutils.core import publish_cmdline, default_description - description = "code-block directive test output" + default_description - try: - import locale - locale.setlocale(locale.LC_ALL, '') - except: - pass - # Uncomment the desired output format: - publish_cmdline(writer_name='pseudoxml', description=description) - # publish_cmdline(writer_name='xml', description=description) - # publish_cmdline(writer_name='html', description=description) - # publish_cmdline(writer_name='latex', description=description) - # publish_cmdline(writer_name='newlatex2e', description=description) - - - diff --git a/sandbox/code-block-directive/docs/pygments_code_block_directive.py.htm b/sandbox/code-block-directive/docs/pygments_code_block_directive.py.htm deleted file mode 100644 index ba7364dbe..000000000 --- a/sandbox/code-block-directive/docs/pygments_code_block_directive.py.htm +++ /dev/null @@ -1,263 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1" ?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> -<meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" /> -<title></title> -<meta name="author" content="a Pygments author|contributor; Felix Wiemann; Guenter Milde" /> -<meta name="date" content="2007-06-08" /> -<meta name="copyright" content="This module has been placed in the public domain." /> -<link rel="stylesheet" href="../../../../lib/python2.4/site-packages/docutils/writers/html4css1/html4css1.css" type="text/css" /> -</head> -<body> -<div class="document"> -<table class="docinfo" frame="void" rules="none"> -<col class="docinfo-name" /> -<col class="docinfo-content" /> -<tbody valign="top"> -<tr><th class="docinfo-name">Author:</th> -<td>a Pygments author|contributor; Felix Wiemann; Guenter Milde</td></tr> -<tr><th class="docinfo-name">Date:</th> -<td>2007-06-08</td></tr> -<tr><th class="docinfo-name">Copyright:</th> -<td>This module has been placed in the public domain.</td></tr> -</tbody> -</table> -<!-- #!/usr/bin/python --> -<p>This is a merge of <a class="reference" href="http://pygments.org/docs/rstdirective/">Using Pygments in ReST documents</a> from the <a class="reference" href="http://pygments.org/">pygments</a> -documentation, and a <a class="reference" href="http://article.gmane.org/gmane.text.docutils.user/3689">proof of concept</a> by Felix Wiemann.</p> -<table border="1" class="docutils"> -<colgroup> -<col width="14%" /> -<col width="86%" /> -</colgroup> -<tbody valign="top"> -<tr><td>2007-06-01</td> -<td>Removed redundancy from class values.</td> -</tr> -<tr><td>2007-06-04</td> -<td>Merge of successive tokens of same type -(code taken from pygments.formatters.others).</td> -</tr> -<tr><td>2007-06-05</td> -<td>Separate docutils formatter script -Use pygments' CSS class names (like the html formatter) -allowing the use of pygments-produced style sheets.</td> -</tr> -<tr><td>2007-06-07</td> -<td>Merge in the formatting of the parsed tokens -(misnamed as docutils_formatter) as class DocutilsInterface</td> -</tr> -<tr><td>2007-06-08</td> -<td>Failsave implementation (fallback to a standard literal block -if pygments not found)</td> -</tr> -</tbody> -</table> -<div class="system-message"> -<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">/usr/src/docutils-svn/sandbox/code-block-directive/pygments_code_block_directive.py.txt</tt>, line 23)</p> -<p>Unknown directive type "code-block".</p> -<pre class="literal-block"> -.. code-block:: - - """Define and register a code-block directive using pygments - """ - -</pre> -</div> -<div class="section"> -<h1><a id="requirements" name="requirements">Requirements</a></h1> -<div class="system-message"> -<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">/usr/src/docutils-svn/sandbox/code-block-directive/pygments_code_block_directive.py.txt</tt>, line 31)</p> -<p>Unknown directive type "code-block".</p> -<pre class="literal-block"> -.. code-block:: - - from docutils import nodes - from docutils.parsers.rst import directives - try: - import pygments - from pygments.lexers import get_lexer_by_name - from pygments.formatters.html import _get_ttype_class - except ImportError: - pass - - - -</pre> -</div> -</div> -<div class="section"> -<h1><a id="customisation" name="customisation">Customisation</a></h1> -<p>Do not insert inline nodes for the following tokens. -(You could add e.g. Token.Punctuation like <tt class="docutils literal"><span class="pre">['',</span> <span class="pre">'p']</span></tt>.)</p> -<div class="system-message"> -<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">/usr/src/docutils-svn/sandbox/code-block-directive/pygments_code_block_directive.py.txt</tt>, line 50)</p> -<p>Unknown directive type "code-block".</p> -<pre class="literal-block"> -.. code-block:: - - unstyled_tokens = [''] - -</pre> -</div> -</div> -<div class="section"> -<h1><a id="docutilsinterface" name="docutilsinterface">DocutilsInterface</a></h1> -<p>This interface class combines code from -pygments.formatters.html and pygments.formatters.others.</p> -<p>It does not require anything of docutils and could also become a part of -pygments</p> -<div class="system-message"> -<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">/usr/src/docutils-svn/sandbox/code-block-directive/pygments_code_block_directive.py.txt</tt>, line 63)</p> -<p>Unknown directive type "code-block".</p> -<pre class="literal-block"> -.. code-block:: - - class DocutilsInterface(object): - """Parse `code` string and yield "classified" tokens. - - Arguments - - code -- string of source code to parse - language -- formal language the code is written in. - - Merge subsequent tokens of the same token-type. - - Yields the tokens as ``(ttype_class, value)`` tuples, - where ttype_class is taken from pygments.token.STANDARD_TYPES and - corresponds to the class argument used in pygments html output. - - """ - - def __init__(self, code, language): - self.code = code - self.language = language - - def lex(self): - # Get lexer for language (use text as fallback) - try: - lexer = get_lexer_by_name(self.language) - except ValueError: - # info: "no pygments lexer for %s, using 'text'"%self.language - lexer = get_lexer_by_name('text') - return pygments.lex(self.code, lexer) - - - def join(self, tokens): - """join subsequent tokens of same token-type - """ - tokens = iter(tokens) - (lasttype, lastval) = tokens.next() - for ttype, value in tokens: - if ttype is lasttype: - lastval += value - else: - yield(lasttype, lastval) - (lasttype, lastval) = (ttype, value) - yield(lasttype, lastval) - - def __iter__(self): - """parse code string and yield "clasified" tokens - """ - try: - tokens = self.lex() - except IOError: - print "INFO: Pygments lexer not found, using fallback" - # TODO: write message to INFO - yield ('', self.code) - return - - for ttype, value in self.join(tokens): - yield (_get_ttype_class(ttype), value) - - - -</pre> -</div> -</div> -<div class="section"> -<h1><a id="code-block-directive" name="code-block-directive">code_block_directive</a></h1> -<div class="system-message"> -<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">/usr/src/docutils-svn/sandbox/code-block-directive/pygments_code_block_directive.py.txt</tt>, line 127)</p> -<p>Unknown directive type "code-block".</p> -<pre class="literal-block"> -.. code-block:: - - def code_block_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - """parse and classify content of a code_block - """ - language = arguments[0] - # create a literal block element and set class argument - code_block = nodes.literal_block(classes=["code-block", language]) - - # parse content with pygments and add to code_block element - for cls, value in DocutilsInterface(u'\n'.join(content), language): - if cls in unstyled_tokens: - # insert as Text to decrease the verbosity of the output. - code_block += nodes.Text(value, value) - else: - code_block += nodes.inline(value, value, classes=[cls]) - - return [code_block] - - -</pre> -</div> -</div> -<div class="section"> -<h1><a id="register-directive" name="register-directive">Register Directive</a></h1> -<div class="system-message"> -<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">/usr/src/docutils-svn/sandbox/code-block-directive/pygments_code_block_directive.py.txt</tt>, line 151)</p> -<p>Unknown directive type "code-block".</p> -<pre class="literal-block"> -.. code-block:: - - code_block_directive.arguments = (1, 0, 1) - code_block_directive.content = 1 - directives.register_directive('code-block', code_block_directive) - -</pre> -</div> -</div> -<div class="section"> -<h1><a id="test-output" name="test-output">Test output</a></h1> -<p>If called from the command line, call the docutils publisher to render the -input</p> -<div class="system-message"> -<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">/usr/src/docutils-svn/sandbox/code-block-directive/pygments_code_block_directive.py.txt</tt>, line 169)</p> -<p>Unknown directive type "code-block".</p> -<pre class="literal-block"> -.. code-block:: - - if __name__ == '__main__': - from docutils.core import publish_cmdline, default_description - description = "code-block directive test output" + default_description - try: - import locale - locale.setlocale(locale.LC_ALL, '') - except: - pass - # Uncomment the desired output format: - publish_cmdline(writer_name='pseudoxml', description=description) - # publish_cmdline(writer_name='xml', description=description) - # publish_cmdline(writer_name='html', description=description) - # publish_cmdline(writer_name='latex', description=description) - # publish_cmdline(writer_name='newlatex2e', description=description) - - - -</pre> -</div> -</div> -</div> -<div class="footer"> -<hr class="footer" /> -<a class="reference" href="pygments_code_block_directive.py.txt">View document source</a>. -Generated on: 2007-06-13. - -</div> -</body> -</html> diff --git a/sandbox/code-block-directive/docs/syntax-highlight.txt b/sandbox/code-block-directive/docs/syntax-highlight.txt index a5d6ffc34..a71cc5b77 100644 --- a/sandbox/code-block-directive/docs/syntax-highlight.txt +++ b/sandbox/code-block-directive/docs/syntax-highlight.txt @@ -3,11 +3,15 @@ Syntax Highlight ================ -:Author: Günter Milde -:Contact: milde@users.berlios.de -:Date: $Date$ -:Abstract: Proposal to add syntax highlight of code blocks to the - capabilities of Docutils_. +:Author: Günter Milde +:Contact: milde@users.berlios.de +:Date: $Date$ +:Copyright: © 2007, 2009 G. Milde, + Released without warranties or conditions of any kind + under the terms of the Apache License, Version 2.0 + http://www.apache.org/licenses/LICENSE-2.0 +:Abstract: Proposal to add syntax highlight of code blocks to the + capabilities of Docutils_. .. sectnum:: .. contents:: @@ -47,10 +51,11 @@ __ http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/252170 a LaTeX package providing highly customisable and advanced syntax highlight, though only for LaTeX (and LaTeX derived PS|PDF). - Since Docutils 0.5, the "latex2e" writer supports - syntax highlight of literal blocks by `listings` with the - ``--literal-block-env=lstlistings`` option. You need to provide a - stylesheet (see also `PyLit Examples`_). + Since Docutils 0.5, the "latex2e" writer supports syntax highlight of + literal blocks by `listings` with the ``--literal-block-env=lstlistings`` + option. You need to provide a custom style sheet. The stylesheets_ + repository provides two LaTeX style sheets for highlighting literal-blocks + with "listings". Trac_ has `reStructuredText support`__ and offers syntax highlighting with @@ -67,12 +72,12 @@ __ http://www.voidspace.org.uk/python/rest2web/macros.html#colorize Sphinx_ features automatic highlighting using the Pygments_ highlighter. - It introduces the custom directives - + It introduces the custom directives + :code-block: similar to the proposal below, :sourcecode: an alias to "code-block", and :highlight: configre highlight of "literal blocks". - + (see http://sphinx.pocoo.org/markup/code.html). Pygments_ @@ -93,8 +98,13 @@ Pygments_ Odtwriter_, experimental writer for Docutils OpenOffice export supports syntax colours using Pygments_. (See the (outdated) section `Odtwriter syntax`_.) -Pygments_ seems to be the most promising docutils highlighter. For printed -output, the listings_ package has its advantages too. +Summary +""""""" + +Pygments_ seems to be the most promising Docutils highlighter. + +For printed output and PDFs via LaTeX, the listings_ package is a viable +alternative. Pygments enhanced docutils front-ends @@ -199,9 +209,6 @@ directive. * The ``code_block_directive`` function inserts the tokens in a "rich" <literal_block> element with "classified" <inline> nodes. -The XML rendering of the small example file `<myfunction.py.txt>`_ looks like -`<myfunction.py.xml>`_. - Writing ''''''' @@ -209,53 +216,51 @@ The writers can use the class information in the <inline> elements to render the tokens. They should ignore the class information if they are unable to use it or to pass it on. +Running the test script `<../tools/test_pygments_code_block_directive.py>`_ +produces example output for a set of writers. + HTML The "html" writer works out of the box. * The rst2html-highlight_ front end registers the "code-block" directive and converts an input file to html. + * Styling is done with the adapted CSS style sheet `pygments-default.css`_ based on docutils' default stylesheet and the output of ``pygmentize -S default -f html``. - + The conversion of `myfunction.py.txt`_ looks like `<myfunction.py.htm>`_. The "s5" and "pep" writers are not tested yet. XML - "xml" and "pseudoxml" work out of the box. - + "xml" and "pseudoxml" work out of the box. + The conversion of `myfunction.py.txt`_ looks like - `<myfunction.py.xml>`_ and `<myfunction.py.pseudoxml>`_ + `<myfunction.py.xml>`_ respective `<myfunction.py.pseudoxml>`_ LaTeX - "latex2e" (SVN version) works out of the box. - - * A style file is required to actually highlight the code in the - output. (As with HTML, the pygments-produced style file will not work - with docutils' output.) - + "latex2e" (SVN version) works out of the box. + + * A style file, e.g. `pygments-docutilsroles.sty`_, is required to actually + highlight the code in the output. (As with HTML, the pygments-produced + style file will not work with docutils' output.) + * Alternatively, the latex writer could reconstruct the original - content and pass it to a ``lstlistings`` environment. - + content and pass it to a ``lstlistings`` environment. + TODO: This should be the default behaviour with ``--literal-block-env=lstlistings``. - - The conversion of `myfunction.py.txt`_ looks like - `<myfunction.py.tex>`_ and converted with pdflatex (without style - sheet) like `<myfunction.py.pdf>`_ - "newlatex2e" produces a valid LaTeX document - (`<myfunction.py.newlatex2e.tex>`_). There is some garbage in the - pdflatex output (`<myfunction.py.newlatex2e.pdf>`_) but this might be - unrelated to the code-block directive. + The LaTeX output of `myfunction.py.txt`_ looks like `<myfunction.py.tex>`_ + and corresponding PDF like `<myfunction.py.pdf>`_. OpenOffice The sandbox project `odtwriter` provided syntax highlight with pygments but used a different syntax and implementation. - - (What is the status of the official `odtwriter` now included in the + + (What is the status of the `odtwriter` now included in the standard distribution?) @@ -268,7 +273,7 @@ TODO place". * add the CSS rules to the default style-sheet (see pygments-default.css_) - + * provide a LaTeX style. 2. Write functional test case and sample. @@ -354,10 +359,10 @@ Odtwriter syntax ---------------- .. attention:: - The content of this section relates to an old version of the + The content of this section relates to an old version of the `odtwriter`. Things changed with the inclusion of the `odtwriter` into standard Docutils. - + This is only kept for historical reasons. Dave Kuhlman's odtwriter_ extension can add syntax highlighting @@ -438,4 +443,4 @@ I.e. the odtwriter implements a `configurable literal block directive`_ .. _pygments_code_block_directive: pygments_code_block_directive-bunt.py.htm .. _rst2html-highlight: ../rst2html-highlight .. _pygments-long.css: ../data/pygments-long.css - +.. _stylesheets: ../../stylesheets/ diff --git a/sandbox/code-block-directive/pygments_code_block_directive.py b/sandbox/code-block-directive/pygments_code_block_directive.py index a0e7d5823..7535acad1 100755 --- a/sandbox/code-block-directive/pygments_code_block_directive.py +++ b/sandbox/code-block-directive/pygments_code_block_directive.py @@ -1,6 +1,6 @@ #!/usr/bin/python -# :Author: a Pygments author|contributor; Felix Wiemann; Guenter Milde +# :Author: the Pygments team; Felix Wiemann; Guenter Milde # :Date: $Date$ # :Copyright: This module has been placed in the public domain. # diff --git a/sandbox/code-block-directive/rst2html-highlight b/sandbox/code-block-directive/rst2html-highlight index 0203c857e..d80b87ec8 100755 --- a/sandbox/code-block-directive/rst2html-highlight +++ b/sandbox/code-block-directive/rst2html-highlight @@ -5,8 +5,8 @@ # # Docutils front-end with syntax highlight. # -# :Author: David Goodger, a Pygments author|contributor, Guenter Milde -# :Date: $Date: $ +# :Author: David Goodger, the Pygments team, Günter Milde +# :Date: $Date: 2008-05-22 08:42:52 +0200 (Do, 22. Mai 2008) $ # :Copyright: This module has been placed in the public domain. # # This is a merge of the docutils_ `rst2html` front end with an extension @@ -24,6 +24,7 @@ Needs an adapted stylesheet # Requirements # ------------ +# # :: try: @@ -46,6 +47,6 @@ description = __doc__ + default_description publish_cmdline(writer_name='html', description=description) # .. _docutils: http://docutils.sf.net/ -# .. _pygments_code_block_directive.py: pygments_code_block_directive.py +# .. _pygments_code_block_directive: pygments_code_block_directive.py # .. _pygments: http://pygments.org/ # .. _Using Pygments in ReST documents: http://pygments.org/docs/rstdirective/ diff --git a/sandbox/code-block-directive/rst2latex-highlight b/sandbox/code-block-directive/rst2latex-highlight new file mode 100755 index 000000000..5f88410bd --- /dev/null +++ b/sandbox/code-block-directive/rst2latex-highlight @@ -0,0 +1,53 @@ +#!/usr/bin/python + +# rst2latex-highlight +# =================== +# +# Docutils front-end with syntax highlight. +# +# :Author: David Goodger, a Pygments author|contributor, Guenter Milde +# :Date: $Date: 2008-05-22 08:42:52 +0200 (Do, 22. Mai 2008) $ +# :Copyright: This module has been placed in the public domain. +# +# This is a merge of the docutils_ `rst2latex` front end with an extension +# suggestion taken from the Pygments_ documentation. +# +# :: + +""" +A front end to docutils, producing LaTeX with syntax colouring using pygments + +Generates LaTeX documents from standalone reStructuredText sources. Uses the +`Pygments` syntax highlighter to parse and mark up the content of ``.. +code-block::` directives. Needs an adapted stylesheet. +""" + +# Requirements +# ------------ +# +# :: + +try: + import locale + locale.setlocale(locale.LC_ALL, '') +except: + pass + +from docutils.core import publish_cmdline, default_description + +# `<pygments_code_block_directive.py>`_ defines and registers a new +# directive `code-block` that uses the `Pygments`_ syntax highlighter to +# render code in color:: + +import pygments_code_block_directive + +# Call the docutils publisher to render the input as latex:: + +description = __doc__ + default_description +publish_cmdline(writer_name='latex2e', description=description) + + +# .. References: +# .. _docutils: http://docutils.sf.net/ +# .. _pygments: http://pygments.org/ +# .. _Using Pygments in ReST documents: http://pygments.org/docs/rstdirective/ diff --git a/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/README.txt b/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/README.txt index 5f5e77557..aa68c3d11 100644 --- a/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/README.txt +++ b/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/README.txt @@ -33,6 +33,10 @@ Disadvantages: - no "minimal" code block marker -- three additional lines per code block +The disadvantages lead to the alternative implementation with the +demonstrator front ends `rst2html-highlight`_ and `rst2latex-highlight`_. + + Example """"""" @@ -54,10 +58,12 @@ Stylesheets: .. _rst2html-pygments: rst2html-pygments .. _rst2latex-pygments: rst2latex-pygments +.. _rst2html-highlight: ../../rst2html-highlight +.. _rst2latex-highlight: ../../rst2latex-highlight .. _for-else-test: .. _for-else-test.py.htm: for-else-test.py.htm .. _for-else-test.py.txt: for-else-test.py.txt .. _for-else-test.py.tex: for-else-test.py.tex .. _for-else-test.py.pdf: for-else-test.py.pdf -.. _pygments-default.css: ../data/pygments-default.css -.. _pygments-default.sty: ../data/pygments-default.sty +.. _pygments-default.css: ../../data/pygments-default.css +.. _pygments-default.sty: ../../data/pygments-default.sty diff --git a/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/for-else-test.py.pdf b/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/for-else-test.py.pdf Binary files differindex b8e63b5e8..fa39a5967 100644 --- a/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/for-else-test.py.pdf +++ b/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/for-else-test.py.pdf diff --git a/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/for-else-test.py.tex b/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/for-else-test.py.tex index b664d4865..e16a5dd71 100644 --- a/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/for-else-test.py.tex +++ b/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/for-else-test.py.tex @@ -1,20 +1,20 @@ -\documentclass[10pt,a4paper,english]{article} +\documentclass[10pt,a4paper,english]{scrartcl} \usepackage{babel} -\usepackage{ae} -\usepackage{aeguill} +\usepackage[T1]{fontenc} \usepackage{shortvrb} -\usepackage[latin1]{inputenc} +\usepackage{ucs} +\usepackage[utf8x]{inputenc} \usepackage{tabularx} \usepackage{longtable} +\usepackage{booktabs} \setlength{\extrarowheight}{2pt} \usepackage{amsmath} \usepackage{graphicx} \usepackage{color} \usepackage{multirow} \usepackage{ifthen} -\usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref} -\usepackage[DIV12]{typearea} -%% generator Docutils: http://docutils.sourceforge.net/ +\typearea{12} +% generated by Docutils <http://docutils.sourceforge.net/> \newlength{\admonitionwidth} \setlength{\admonitionwidth}{0.9\textwidth} \newlength{\docinfowidth} @@ -55,7 +55,11 @@ \newcommand{\rubric}[1]{\subsection*{~\hfill {\it #1} \hfill ~}} \newcommand{\titlereference}[1]{\textsl{#1}} % end of "some commands" -\input{pygments-default.sty} +% user specified packages and stylesheets: +\usepackage{../../data/pygments-default} +\ifthenelse{\isundefined{\hypersetup}}{ +\usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref} +}{} \title{Example for syntax highlight with Pygments} \author{} \date{} @@ -66,22 +70,33 @@ pdftitle={Example for syntax highlight with Pygments} \begin{document} \maketitle - \setlength{\locallinewidth}{\linewidth} -% # -*- rst-mode -*- Translate this document to HTML with a pygments enhanced frontend: -\begin{quote}{\ttfamily \raggedright \noindent -rst2html-pygments~-{}-stylesheet=pygments-default.css -}\end{quote} +\begin{quote}\begin{verbatim} +rst2html-pygments --stylesheet=pygments-default.css +\end{verbatim} +\end{quote} or to LaTeX with: -\begin{quote}{\ttfamily \raggedright \noindent -rst2latex-pygments~-{}-stylesheet=pygments-default.sty -}\end{quote} +\begin{quote}\begin{verbatim} +rst2latex-pygments --stylesheet=pygments-default.sty +\end{verbatim} +\end{quote} to gain syntax highlight in the output. -% Run the doctests with ``pylit --doctest for-else-test.py``. + +Convert between text {\textless}-{\textgreater} code source formats with: +\begin{quote}\begin{verbatim} +pylit --code-block-marker='.. code-block:: python' +\end{verbatim} +\end{quote} + +Run the doctests with: +\begin{quote}\begin{verbatim} +pylit --doctest for-else-test.py +\end{verbatim} +\end{quote} %___________________________________________________________________________ @@ -89,78 +104,67 @@ to gain syntax highlight in the output. \hypertarget{for-else-test}{} \pdfbookmark[0]{for-else-test}{for-else-test} \section*{for-else-test} +\label{for-else-test} Test the flow in a \titlereference{for} loop with \titlereference{else} statement. First define a simple \titlereference{for} loop. \begin{Verbatim}[commandchars=@\[\]] -@Cax[def] @CaJ[loop1](iterable): - @Car["""simple for loop with `else` statement"""] - @Cax[for] i @Cam[in] iterable: - @Cax[print] i - @Cax[else]: - @Cax[print] @Cad["]@Cad[iterable empty]@Cad["] - @Cax[print] @Cad["]@Cad[Ende]@Cad["] - +@PYay[def] @PYaK[loop1](iterable): + @PYas["""simple for loop with `else` statement"""] + @PYay[for] i @PYan[in] iterable: + @PYay[print] i + @PYay[else]: + @PYay[print] @PYad["]@PYad[iterable empty]@PYad["] + @PYay[print] @PYad["]@PYad[Ende]@PYad["] \end{Verbatim} Now test it: The first test runs as I expect: iterator empty -{\textgreater} else clause applies: \begin{Verbatim}[commandchars=@\[\]] -@CaN[>>> ]loop1(@CaW[range](@Cag[0])) -@Caa[iterable empty] -@Caa[Ende] - +@PYaO[>>> ]@PYaX[execfile](@PYad[']@PYad[for-else-test.py]@PYad[']) +@PYaO[>>> ]loop1(@PYaX[range](@PYaw[0])) +@PYaa[iterable empty] +@PYaa[Ende] \end{Verbatim} However, the else clause even runs if the iterator is not empty in the first place but after it is ``spent'': \begin{Verbatim}[commandchars=@\[\]] -@CaN[>>> ]loop1(@CaW[range](@Cag[3])) -@Caa[0] -@Caa[1] -@Caa[2] -@Caa[iterable empty] -@Caa[Ende] - +@PYaO[>>> ]loop1(@PYaX[range](@PYaw[3])) +@PYaa[0] +@PYaa[1] +@PYaa[2] +@PYaa[iterable empty] +@PYaa[Ende] \end{Verbatim} It seems like the else clause can only be prevented, if we break out of the loop. Let's try \begin{Verbatim}[commandchars=@\[\]] -@Cax[def] @CaJ[loop2](iterable): - @Car["""for loop with `break` and `else` statement"""] - @Cax[for] i @Cam[in] iterable: - @Cax[print] i - @Cax[break] - @Cax[else]: - @Cax[print] @Cad["]@Cad[iterable empty]@Cad["] - @Cax[print] @Cad["]@Cad[Ende]@Cad["] - +@PYay[def] @PYaK[loop2](iterable): + @PYas["""for loop with `break` and `else` statement"""] + @PYay[for] i @PYan[in] iterable: + @PYay[print] i + @PYay[break] + @PYay[else]: + @PYay[print] @PYad["]@PYad[iterable empty]@PYad["] + @PYay[print] @PYad["]@PYad[Ende]@PYad["] \end{Verbatim} And indeed, the else clause is skipped after breaking out of the loop: \begin{Verbatim}[commandchars=@\[\]] -@CaN[>>> ]loop2(@CaW[range](@Cag[3])) -@Caa[0] -@Caa[Ende] - +@PYaO[>>> ]loop2(@PYaX[range](@PYaw[3])) +@PYaa[0] +@PYaa[Ende] \end{Verbatim} The empty iterator runs as expected: \begin{Verbatim}[commandchars=@\[\]] -@CaN[>>> ]loop2(@CaW[range](@Cag[0])) -@Caa[iterable empty] -@Caa[Ende] - +@PYaO[>>> ]loop2(@PYaX[range](@PYaw[0])) +@PYaa[iterable empty] +@PYaa[Ende] \end{Verbatim} -\begin{center}\small - -Generated on: 2007-04-24. - - -\end{center} - \end{document} diff --git a/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/rst2html-pygments b/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/rst2html-pygments index c227bbf2e..706b25980 100755 --- a/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/rst2html-pygments +++ b/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/rst2html-pygments @@ -1,6 +1,6 @@ #!/usr/bin/python -# :Author: David Goodger, a Pygments author|contributor, Guenter Milde +# :Author: David Goodger, the Pygments team, Guenter Milde # :Date: $Date: $ # :Copyright: This module has been placed in the public domain. diff --git a/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/rst2latex-pygments b/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/rst2latex-pygments index f52fc167f..c53c2aa74 100755 --- a/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/rst2latex-pygments +++ b/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/rst2latex-pygments @@ -1,6 +1,6 @@ #!/usr/bin/python -# Author: David Goodger, a Pygments author|contributor, Guenter Milde +# Author: David Goodger, the Pygments team, Günter Milde # Date: $Date: $ # Copyright: This module has been placed in the public domain. diff --git a/sandbox/code-block-directive/tools/test_pygments_code_block_directive.py b/sandbox/code-block-directive/tools/test_pygments_code_block_directive.py index b130a7b2f..9d0ea510a 100755 --- a/sandbox/code-block-directive/tools/test_pygments_code_block_directive.py +++ b/sandbox/code-block-directive/tools/test_pygments_code_block_directive.py @@ -3,7 +3,7 @@ # Test the parsing and formatting by pygments: -# :Author: Felix Wiemann; Guenter Milde +# :Author: Felix Wiemann; Günter Milde # :Date: $Date$ # :Copyright: This module has been placed in the public domain. @@ -11,6 +11,13 @@ # ------------ from docutils import nodes, utils, core + +# Prepend parent dir to the PYTHONPATH (This is a hack to get this test +# working without installing the pygments_code_block_directive module. +# Not needed if the module is installed in the PYTHONPATH) +import sys +sys.path.insert(0, '..') + from pygments_code_block_directive import DocutilsInterface # Test data @@ -51,7 +58,7 @@ for cls, value in DocutilsInterface(code_sample, language): # ----- writer_names = ('html', 'pseudoxml', 'xml', 'latex', 'newlatex2e', 's5') -for name in writer_names[2:3]: +for name in writer_names[:]: print "\nusing writer %r\n" % name print core.publish_from_doctree(document, writer_name=name) |