Revert 'Remove Lore' -- empty directories left over. Reopens: twisted…

…#7892 git-svn-id: svn://svn.twistedmatrix.com/svn/Twisted/trunk@44834 bbbe8e31-12d6-0310-92fd-ac37d47ddeeb
yuankui · May 16, 2015 · 4be4e80 · 4be4e80
1 parent a992d7c
commit 4be4e80
Show file tree

Hide file tree

Showing 75 changed files with 9,966 additions and 10 deletions.
diff --git a/admin/update-documentation.py b/admin/update-documentation.py
@@ -0,0 +1,33 @@
+#!/usr/bin/env python
+# Copyright (c) Twisted Matrix Laboratories.
+# See LICENSE for details.
+
+import sys
+from twisted.python import filepath
+
+def updateDocumentation(project, twistedCheckoutPath, websiteCheckoutPath):
+    """
+    Copy documentation for a particular project out of the craphole where lore
+    dumps it, and into a WebSite working copy.
+
+    @param generatedDocPath: The path to the root of a Twisted checkout, ie
+    ~/Projects/Twisted/tags/releases/TwistedWeb/0.5.x/
+
+    @param websiteCheckoutPath: The path to the root of a WebSite checkout, ie
+    ~/Projects/WebSite/branches/update-web-docs-123/
+    """
+    docPath = twistedCheckoutPath.child('doc').child(project)
+    minusSVN = docPath.temporarySibling()
+    docPath.copyTo(minusSVN)
+    for child in minusSVN.walk():
+        if child.basename() == '.svn':
+            child.remove()
+
+    minusSVN.copyTo(websiteCheckoutPath.child('vhosts').child('twistedmatrix.com').child('projects').child(project).child('documentation'))
+    minusSVN.remove()
+
+
+if __name__ == '__main__':
+    if len(sys.argv) != 4:
+        raise SystemExit("Usage: %s <project> <twisted checkout root> <website checkout root>" % (sys.argv[0],))
+    updateDocumentation(sys.argv[1], filepath.FilePath(sys.argv[2]), filepath.FilePath(sys.argv[3]))
diff --git a/bin/lore/lore b/bin/lore/lore
@@ -0,0 +1,16 @@
+#!/usr/bin/env python
+# Copyright (c) Twisted Matrix Laboratories.
+# See LICENSE for details.
+
+import sys, os
+extra = os.path.dirname(os.path.dirname(sys.argv[0]))
+sys.path.insert(0, extra)
+try:
+    import _preamble
+except ImportError:
+    sys.exc_clear()
+sys.path.remove(extra)
+
+from twisted.lore.scripts.lore import run
+run()
+
diff --git a/docs/core/development/policy/svn-dev.rst b/docs/core/development/policy/svn-dev.rst
@@ -218,14 +218,76 @@ the last developer who touched that file.
 Building docs
 -------------
 
-Twisted documentation (not including the automatically-generated API docs) is generated by `Sphinx <http://sphinx-doc.org/>`_ .
-The docs are written in Restructured Text (``.rst``) and translated into ``.html`` files by the ``bin/admin/build-docs`` script.
 
-To build the HTML form of the docs into the ``doc/`` directory, do the following:
+
+Twisted documentation (not including the automatically-generated API docs)
+is in `Lore Format <http://twistedmatrix.com/trac/wiki/TwistedLore>`_ .
+These ``.xhtml`` files are translated into ``.html`` files by
+the "bin/lore/lore" script, which can check the files for syntax problems
+(hlint), process multiple files at once, insert the files into a template
+before processing, and can also translate the files into LaTeX or PostScript
+instead.
+
+
+
+
+To build the HTML form of the howto/ docs, do the following. Note that
+the index file will be placed in ``doc/core/howto/index.html`` .
+
+
+
+
+
+.. code-block:: console
+
+    
+    ./bin/lore/lore -p --config template=doc/core/howto/template.tpl doc/core/howto/*.xhtml
+
+
+
+
+To run hlint over a single Lore document, such as ``doc/development/policy/svn-dev.xhtml`` , do the following. This is
+useful because the HTML conversion may bail without a useful explanation if
+it sees mismatched tags.
+
+
+
+
 
 .. code-block:: console
 
-    ./bin/admin/build-docs .
+    
+    ./bin/lore/lore -n --output lint doc/development/policy/svn-dev.xhtml
+
+
+
+
+To convert it to HTML (including markup, interpolation of examples,
+footnote processing, etc), do the following. The results will be placed in ``doc/development/policy/svn-dev.html`` :
+
+
+
+
+
+.. code-block:: console
+
+    
+    ./bin/lore/lore -p --config template=doc/core/howto/template.tpl \
+       doc/development/policy/svn-dev.xhtml
+
+
+
+
+Note that hyperlinks to other documents may not be quite right unless you
+include a "-l" argument to ``bin/lore/lore`` . Links in the
+.xhtml file are to .xhtml targets: when the .xhtml is turned into .html, the
+link targets are supposed to be turned into .html also. In addition to this,
+Lore markup of the form ``<code class="API">`` is supposed to
+turn into a link to the corresponding API reference page. These links will
+probably be wrong unless the correct base URL is provided to Lore.
+
+
+
 
 
 Committing and Post-commit Hooks

diff --git a/docs/core/howto/book.tex b/docs/core/howto/book.tex
@@ -0,0 +1,129 @@
+\documentclass[oneside]{book}
+\usepackage[dvips]{graphicx}
+\usepackage{times,mathptmx}
+\usepackage{ifthen}
+\usepackage{hyperref}
+
+\usepackage{geometry}
+\geometry{verbose,letterpaper,tmargin=1in,bmargin=0.5in,lmargin=1in,rmargin=1in}
+
+\setlength{\oddsidemargin}{0in}
+\setlength{\textwidth}{\paperwidth}
+\addtolength{\textwidth}{-2in}
+
+\newcommand{\loreref}[1]{%
+    \ifthenelse{\value{page}=\pageref{#1}}%
+               { (this page)}%
+               { (page \pageref{#1})}%
+}
+
+
+\title{The Twisted Documentation}
+\author{The Twisted Development Team}
+
+\tolerance=1000
+\sloppy
+
+\begin{document}
+\maketitle
+\tableofcontents
+
+\chapter{Introduction}
+
+\input{vision.tex}
+
+
+\chapter{Getting Started}
+
+\input{servers.tex}
+\input{clients.tex}
+\input{trial.tex}
+\input{tutorial/index.tex}
+\input{tutorial/intro.tex}
+\input{tutorial/protocol.tex}
+\input{tutorial/style.tex}
+\input{tutorial/components.tex}
+\input{tutorial/backends.tex}
+\input{tutorial/web.tex}
+\input{tutorial/pb.tex}
+\input{tutorial/factory.tex}
+\input{tutorial/client.tex}
+\input{tutorial/library.tex}
+\input{tutorial/configuration.tex}
+\input{quotes.tex}
+\input{design.tex}
+
+
+\chapter{Networking and Other Event Sources}
+
+\input{internet-overview.tex}
+\input{reactor-basics.tex}
+\input{ssl.tex}
+\input{udp.tex}
+\input{process.tex}
+\input{defer.tex}
+\input{gendefer.tex}
+\input{time.tex}
+\input{threading.tex}
+\input{producers.tex}
+\input{choosing-reactor.tex}
+
+
+\chapter{High-Level Infrastructure}
+
+\input{endpoints.tex}
+\input{components.tex}
+\input{cred.tex}
+\input{plugin.tex}
+
+
+\chapter{Deploying Twisted Applications}
+
+\input{basics.tex}
+\input{application.tex}
+\input{tap.tex}
+
+
+\chapter{Utilities}
+
+\input{logging.tex}
+\input{constants.tex}
+\input{rdbms.tex}
+\input{options.tex}
+\input{dirdbm.tex}
+\input{testing.tex}
+
+
+\chapter{Asynchronous Messaging Protocol (AMP)}
+
+\input{amp.tex}
+
+
+\chapter{Perspective Broker}
+
+\input{pb.tex}
+\input{pb-intro.tex}
+\input{pb-usage.tex}
+\input{pb-clients.tex}
+\input{pb-copyable.tex}
+\input{pb-cred.tex}
+\input{pb-limits.tex}
+
+
+\chapter{Manual Pages}
+
+\input{../man/trial-man.tex}
+\clearpage
+\input{../man/twistd-man.tex}
+\clearpage
+\input{../man/tap2deb-man.tex}
+\clearpage
+\input{../man/tap2rpm-man.tex}
+
+
+\chapter{Appendix}
+
+\input{glossary.tex}
+\input{debug-with-emacs.tex}
+
+\end{document}
diff --git a/docs/core/howto/glossary.rst b/docs/core/howto/glossary.rst
@@ -331,12 +331,25 @@ Jelly
 
 
 
-
+  
   The serialization layer for :ref:`Twisted Spread <core-howto-glossary-spread>` , although it
   can be used separately from Twisted Spread as well.  It is similar in purpose
   to Python's standard ``pickle`` module, but is more
   network-friendly, and depends on a separate marshaller (:ref:`Banana <core-howto-glossary-banana>` , in most cases).  See :api:`twisted.spread.jelly <twisted.spread.jelly>` .
 
+.. _core-howto-glossary-lore:
+
+Lore
+
+
+
+
+
+
+  `Lore <http://twistedmatrix.com/trac/wiki/TwistedLore/>`_ is
+  Twisted's documentation system.  The source format is a subset of
+  XHTML, and output formats include HTML and LaTeX.
+
 .. _core-howto-glossary-manhole:
 
 Manhole

diff --git a/docs/index.rst b/docs/index.rst
@@ -10,6 +10,7 @@ Contents:
     installation/index
     core/index
     conch/index
+    lore/index
     mail/index
     names/index
     pair/index

diff --git a/docs/lore/examples/example.html b/docs/lore/examples/example.html
@@ -0,0 +1,60 @@
+<?xml version="1.0"?>
+<!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">
+
+<head>
+<title>Your Title Here</title>
+</head>
+
+<body>
+<h1>Your Title Here</h1>
+
+<h2>Introduction</h2>
+
+<p>The introduction is an important part of your
+document<span class="footnote">though it should not be the most important
+part</span>.</p>
+
+<div class="note">
+<p>It is generally a <em>very</em> good to write other section except
+the introduction too.</p>
+</div>
+
+<p>
+You can use the following ways to write lists:
+<ul>
+<li>Unordered lists</li>
+<li>
+    <ol>
+    <li>ordered lists</li>
+    </ol>
+</li>
+<li><dl>
+    <dt>defintion lists</dt>
+    <dd>with definitions</dd>
+    </dl>
+</li>
+</ul>
+</p>
+
+<p>Shell commands look like <code class="shell">ls -l</code>. Python
+snippets look like <code class="python">print 1</code>.</p>
+
+<p>Longer python things should be in pre</p>
+
+<pre class="python">
+def foo():
+    pass
+</pre>
+
+<p>Or they can be outlined</p>
+
+<a href="rootscript.py" class="py-listing">rootscript.py</a>
+
+<p>Likewise, HTML can be outlined too:</p>
+
+<a href="example.html" class="py-listing">example.html</a>
+
+</body> </html>
diff --git a/docs/lore/examples/index.rst b/docs/lore/examples/index.rst
@@ -0,0 +1,10 @@
+
+:LastChangedDate: $LastChangedDate$
+:LastChangedRevision: $LastChangedRevision$
+:LastChangedBy: $LastChangedBy$
+
+Examples
+========
+
+- `example.html <example.html>`_
+- `slides-template.tpl <slides-template.tpl>`_
diff --git a/docs/lore/examples/slides-template.tpl b/docs/lore/examples/slides-template.tpl
@@ -0,0 +1,21 @@
+<?xml version="1.0"?>
+<!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" lang="en">
+  <head>
+    <title>Twisted Documentation: </title>
+    <link type="text/css" rel="stylesheet" href="stylesheet.css" />
+  </head>
+
+  <body bgcolor="white">
+    <div><span>Previous: <a class="previous"><span class="previous" /></a></span>
+         <br />
+	 <span>Next: <a class="next"><span class="next" /></a></span></div>
+    <h1 class="title"></h1>
+    <div class="body">
+
+    </div>
+  </body>
+</html>
+