~hudson-openstack/nova/trunk

<?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 lang="en" xmlns="http://www.w3.org/1999/xhtml">

<head>

<title>Twisted Documentation: Extending the Lore Documentation System</title>

</head>

<h1 class="title">Extending the Lore Documentation System</h1>

<div class="toc"><ol><li><a href="#auto0">Overview</a></li><li><a href="#auto1">Inputs and Outputs</a></li><ul><li><a href="#auto2">Creating New Inputs</a></li></ul></ol></div>

<h2>Overview<a name="auto0"/></h2>

The <a href="lore.html" shape="rect">Lore Documentation System</a>, out of the box, is

specialized for documenting Twisted. Its markup includes CSS classes for

Python, HTML, filenames, and other Twisted-focused categories. But don't

think this means Lore can't be used for other documentation tasks! Lore is

designed to allow extensions, giving any Python programmer the ability to

customize Lore for documenting almost anything.

There are several reasons why you would want to extend Lore. You may want

to attach file formats Lore does not understand to your documentation. You

may want to create callouts that have special meanings to the reader, to give a

memorable appearance to text such as, <q>WARNING: This software was written by

a frothing madman!</q> You may want to create color-coding for a different

programming language, or you may find that Lore does not provide you with

enough structure to mark your document up completely. All of these situations

can be solved by creating an extension.

<h2>Inputs and Outputs<a name="auto1"/></h2>

Lore works by reading the HTML source of your document, and producing

whatever output the user specifies on the command line. If the HTML document

is well-formed XML that meets a certain minimum standard, Lore will be able to

to produce some output. All Lore extensions will be written to redefine the

input, and most will redefine the output in some way. The name of

the default input is <q>lore</q>. When you write your extension, you will

come up with a new name for your input, telling Lore what rules to use to

process the file.

Lore can produce XHTML, LaTeX, and DocBook document formats, which can be

displayed directly if you have a user agent capable of viewing them, or

processed into a third form such as PostScript or PDF. Another output is

called <q>lint</q>, after the static-checking utility for C, and is used for

the same reason: to statically check input files for problems. The

<q>lint</q> output is just a stream of error messages, not a formatted

document, but is important because it gives users the ability to validate

their input before trying to process it. For the first example, the only

output we will be concerned with is LaTeX.

<h3>Creating New Inputs<a name="auto2"/></h3>

Create a new input to tell Lore that your document is marked up differently

from a vanilla Lore document. This gives you the power to define a new tag

class, for example:

The Frabjulon Limpet 2000

is the industry-leading aquatic

mollusc counter, bar none.

</pre>

The above HTML is an instance of a new input to Lore, which we will call

MyHTML, to differentiate it from the <q>lore</q> input. We want it to have

the following markup:

<ul>

<li>A <code>productname</code> class for the tag, which

produces underlined text</li>

<li>A <code>marketinglie</code> class for tag, which

produces larger type, bold text</li>

</ul>

Note that I chose class names that are valid Python identifiers. You will

see why shortly. To get these two effects in Lore's HTML output, all we have

to do is create a cascading stylesheet (CSS), and use it in the Lore XHTML

Template. However, we also want these effects to work in LaTeX, and we want

the output of lint to produce no warnings when it sees lines with these 2

classes. To make LaTeX and lint work, we start by creating a plugin.

<div class="py-listing"><pre> 1

from zope.interface import implements

from twisted.plugin import IPlugin

from twisted.lore.scripts.lore import IProcessor

class MyHTML(object):

implements(IPlugin, IProcessor)

name = "myhtml"

moduleName = "myhtml.factory"

</pre><div class="caption">

100

Listing 1: The Plugin File - <a href="listings/lore/a_lore_plugin.py">listings/lore/a_lore_plugin.py</a></div></div>

101

102

Create this file in a <code class="shell">twisted/plugins/</code>

103

directory (not a package) which is located in a directory in the

104

Python module search path. See the <a href="../../core/howto/plugin.html" shape="rect">Twisted

105

plugin howto</a> for more details on plugins.

106

107

Users of your extension will pass the value of your plugin's <code class="python">name</code> attribute to lore with the <code class="shell">--input</code> parameter on the command line to select it. For

108

example, to select the plugin defined above, a user would pass <code class="shell">--input myhtml</code>. The <code class="python">moduleName</code> attribute tells Lore where to find the code

109

implementing the plugin. In particular, this module should have a <code class="python">factory</code> attribute which defines a <code class="python">generator_</code>-prefixed method for each output format it

110

supports. Next we'll look at this module.

111

112

<div class="py-listing"><pre>1

113

114

115

116

117

118

119

120

121

from twisted.lore import default

122

from myhtml import spitters

123

124

class MyProcessingFunctionFactory(default.ProcessingFunctionFactory):

125

latexSpitters={None: spitters.MyLatexSpitter,

126

}

127

128

# initialize the global variable factory with an instance of your new factory

129

factory=MyProcessingFunctionFactory()

130

</pre><div class="caption">Listing 2: The Input

131

Factory - <a href="listings/lore/factory.py-1">listings/lore/factory.py-1</a></div></div>

132

133

In Listing 2, we create a subclass of ProcessingFunctionFactory. This

134

class provides a hook for you, a class variable named

135

<code>latexSpitters</code>. This variable tells Lore

136

what new class will be generating LaTeX from your input format. We redefine

137

<code>latexSpitters</code> to <code>MyLatexSpitter</code> in the subclass

138

because this

139

class knows what to do with the new input we have already defined. Last, you

140

must define the module-level variable <code class="py-src-identifier">factory</code>. It should be an instance with

141

the same

142

interface as <code class="py-src-identifier">ProcessingFunctionFactory</code>

143

(e.g. an instance of a subclass, in this case, <code class="py-src-identifier">MyProcessingFunctionFactory</code>).

144

145

Now let's actually write some code to generate the LaTeX. Doing this

146

requires at least a familiarity with the LaTeX language. Search Google for

147

<q>latex tutorial</q> and you will find any number of useful LaTeX

148

resources.

149

150

<div class="py-listing"><pre> 1

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

from twisted.lore.latex import processFile

170

import os.path

171

172

class MyLatexSpitter(latex.LatexSpitter):

173

def visitNode_span_productname(self, node):

174

# start an underline section in LaTeX

175

self.writer('\\underline{')

176

# process the node and its children

177

self.visitNodeDefault(node)

178

# end the underline block

179

self.writer('}')

180

181

def visitNode_span_marketinglie(self, node):

182

# this example turns on more than one LaTeX effect at once

183

self.writer('\\begin{bf}\\begin{Large}')

184

self.visitNodeDefault(node)

185

self.writer('\\end{Large}\\end{bf}')

186

</pre><div class="caption">Listing 3:

187

spitters.py - <a href="listings/lore/spitters.py-1">listings/lore/spitters.py-1</a></div></div>

188

189

The method <code>visitNode_span_productname</code> is

190

our handler for tags with the <code>class="productname"</code>

191

identifier. Lore knows to try methods <code>visitNode_span_*</code> and

192

<code>visitNode_div_*</code> whenever it encounters a new

193

class in one of these tags. This is why the class names have to be valid

194

Python identifiers.

195

196

Now let's see what Lore does with these new classes with the following

197

input file:

198

199

200

<html>

201

<head>

202

<title>My First Example</title>

203

</head>

204

<body>

205

<h1>My First Example</h1>

206

The Frabjulon Limpet 2000

207

is the industry-leading aquatic

208

mollusc counter, bar none.

209

</body>

210

</html>

211

212

</pre><div class="caption">Listing 4:

213

1st_example.html - <a href="listings/lore/1st_example.html">listings/lore/1st_example.html</a></div></div>

214

215

First, verify that your package is laid out correctly. Your directory

216

structure should look like this:

217

218

219

1st_example.html

220

myhtml/

221

__init__.py

222

factory.py

223

spitters.py

224

twisted/plugins/

225

a_lore_plugin.py

226

</pre>

227

228

In the parent directory of myhtml (that is, <code>myhtml/..</code>), run

229

lore and pdflatex on the input:

230

231

232

$ lore --input myhtml --output latex 1st_example.html

233

[########################################] (*Done*)

234

235

$ pdflatex 1st_example.tex

236

[ . . . latex output omitted for brevity . . . ]

237

Output written on 1st_example.pdf (1 page, 22260 bytes).

238

Transcript written on 1st_example.log.

239

</pre>

240

241

And here's what the rendered PDF looks like:

242

243

244

245

What happens when we run lore on this file using the lint output?

246

247

248

$ lore --input myhtml --output lint 1st_example.html

249

1st_example.html:7:47: unknown class productname

250

1st_example.html:8:38: unknown class marketinglie

251

[########################################] (*Done*)

252

</pre>

253

254

Lint reports these classes as errors, even though our spitter knows how to

255

process them. To fix this problem, we must add to <code class="py-filename">factory.py</code>.

256

257

<div class="py-listing"><pre> 1

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

from myhtml import spitters

279

280

281

latexSpitters={None: spitters.MyLatexSpitter,

282

}

283

284

# redefine getLintChecker to validate our classes

285

def getLintChecker(self):

286

# use the default checker from parent

287

checker = lint.getDefaultChecker()

288

checker.allowedClasses = checker.allowedClasses.copy()

289

oldSpan = checker.allowedClasses['span']

290

checkfunc=lambda cl: oldSpan(cl) or cl in ['marketinglie',

291

'productname']

292

checker.allowedClasses['span'] = checkfunc

293

return checker

294

295

# initialize the global variable factory with an instance of your new factory

296

factory=MyProcessingFunctionFactory()

297

</pre><div class="caption">Listing 5: Input

298

Factory with Lint Support - <a href="listings/lore/factory.py-2">listings/lore/factory.py-2</a></div></div>

299

300

The method <code class="py-src-identifier">getLintChecker</code> is called

301

by Lore to produce the lint output. This modification adds our classes to the

302

list of classes lint ignores:

303

304

305

$ lore --input myhtml --output lint 1st_example.html

306

[########################################] (*Done*)

307

$ # Hooray!

308

</pre>

309

310

Finally, there are two other sub-outputs of LaTeX, for a total of three

311

different ways that Lore can produce LaTeX: the default way, which produces as

312

output an entire, self-contained LaTeX document; with <code class="shell">--config section</code> on the command line, which produces a

313

LaTeX \section; and with <code class="shell">--config chapter</code>, which

314

produces a LaTeX \chapter. To support these options as well, the solution is

315

to make the new spitter class a mixin, and use it with the <code class="py-src-identifier">SectionLatexSpitter</code> and <code class="py-src-identifier">ChapterLatexSpitter</code>, respectively.

316

Comments in the following listings tell you everything you need to know about

317

making these simple changes:

318

319

<ul>

320

<li><div class="py-listing"><pre> 1

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

from myhtml import spitters

343

344

345

# 1. add the keys "chapter" and "section" to latexSpitters to handle the

346

# --config chapter and --config section options

347

latexSpitters={None: spitters.MyLatexSpitter,

348

"section": spitters.MySectionLatexSpitter,

349

"chapter": spitters.MyChapterLatexSpitter,

350

}

351

352

def getLintChecker(self):

353

checker = lint.getDefaultChecker()

354

355

oldSpan = checker.allowedClasses['span']

356

357

'productname']

358

checker.allowedClasses['span'] = checkfunc

359

return checker

360

361

factory=MyProcessingFunctionFactory()

362

</pre><div class="caption">factory.py - <a href="listings/lore/factory.py-3">listings/lore/factory.py-3</a></div></div></li>

363

<li><div class="py-listing"><pre> 1

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

from twisted.lore.latex import processFile

391

import os.path

392

393

# 2. Create a new mixin that does what the old MyLatexSpitter used to do:

394

# process the new classes we defined

395

class MySpitterMixin:

396

def visitNode_span_productname(self, node):

397

self.writer('\\underline{')

398

self.visitNodeDefault(node)

399

self.writer('}')

400

401

def visitNode_span_marketinglie(self, node):

402

self.writer('\\begin{bf}\\begin{Large}')

403

self.visitNodeDefault(node)

404

self.writer('\\end{Large}\\end{bf}')

405

406

# 3. inherit from the mixin class for each of the three sub-spitters

407

class MyLatexSpitter(MySpitterMixin, latex.LatexSpitter):

408

pass

409

410

class MySectionLatexSpitter(MySpitterMixin, latex.SectionLatexSpitter):

411

pass

412

413

class MyChapterLatexSpitter(MySpitterMixin, latex.ChapterLatexSpitter):

414

pass

415

</pre><div class="caption">spitters.py - <a href="listings/lore/spitters.py-2">listings/lore/spitters.py-2</a></div></div></li>

416

</ul>

417

418

419

420

</div>

421

422

<a href="index.html">Index</a>

423

Version: 10.0.0

424

</body>

425

</html>

b'\\ No newline at end of file'

Older »