[Python-checkins] r61423 - doctools/trunk/HACKING doctools/trunk/README

Sun Mar 16 14:06:12 CET 2008

Author: georg.brandl
Date: Sun Mar 16 14:06:12 2008
New Revision: 61423

Removed:
   doctools/trunk/HACKING
   doctools/trunk/README
Log:
Remove obsolete documents.


Deleted: /doctools/trunk/HACKING
==============================================================================

--- /doctools/trunk/HACKING	Sun Mar 16 14:06:12 2008
+++ (empty file)
@@ -1,142 +0,0 @@
-.. -*- mode: rst -*-
-
-===============
-Coding overview
-===============
-
-This document tries to give you a cursory overview of the doctools code.
-
-TODO: update this.
-
-
-Dependencies
-------------
-
-The converter doesn't have any dependencies except Python 2.5.
-
-Sphinx needs Python 2.5, Docutils 0.4 (not SVN, because of API changes), Jinja
->= 1.1 (which is at the moment included as an SVN external) and Pygments >= 0.8
-(which is optional and can be installed from the cheese shop).
-
-
-The converter
--------------
-
-There's not too much to say about the converter.  It's quite as finished as
-possible, and as it has to only work with the body of documentation found in the
-Python core, it doesn't have to be as general as possible.
-
-(If other projects using the LaTeX documentation toolchain want to convert their
-docs to the new format, the converter will probably have to be amended.)
-
-In ``restwriter.py``, there's some commentary about the inner works of the
-converter concerning a single file.
-
-The ``filenamemap.py`` file tells the converter how to rearrange the converted
-files in the reST source directories.  There, for example, the tutorial is split
-up in several files, and old or unusable files are flagged as not convertable.
-Also, non-LaTeX files, such as code include files, are listed to be copied into
-corresponding directories.
-
-The directory ``newfiles`` contains a bunch of files that didn't exist in the
-old distribution, such as the documentation of Sphinx markup, that will be
-copied to the reST directory too.
-
-
-Sphinx
-------
-
-Sphinx consists of two parts:
-
-* The builder takes the reST sources and converts them into an output format.
-  (Presently, HTML, HTML Help or webapp-usable pickles.)
-
-* The web application takes the webapp-usable pickles, which mainly contain the
-  HTML bodies converted from reST and some additional information, and turns them
-  into a WSGI application, complete with commenting, navigation etc.
-  (The subpackage ``web`` is responsible for this.)
-
-An overview of the source files:
-
-addnodes.py
-  Contains docutils node classes that are not part of standard docutils.  These
-  node classes must be handled by every docutils writer that gets one of our
-  nodetrees.
-
-  (The docutils parse a reST document into a tree of "nodes". This nodetree can
-  then be converted into an internal representation, XML or anything a Writer
-  exists for.)
-
-builder.py
-  Contains the Builder classes, which are responsible for the process of building
-  the output files from docutils node trees.
-
-  The builder is called by ``sphinx-build.py``.
-
-directives.py
-  Directive functions that transform our custom directives (like ``.. function::``)
-  into doctree nodes.
-
-environment.py
-  The "build environment", a class that holds metadata about all doctrees, and is
-  responsible for building them out of reST source files.
-
-  The environment is stored, in a pickled form, in the output directory, in
-  order to enable incremental builds if only a few source files change, which
-  usually is the case.
-
-highlighting.py
-  Glue to the Pygments highlighting library.  Will use no highlighting at all if
-  that is not installed.  Probably a stripped down version of the Pygments Python
-  lexer and HTML formatter could be included.
-
-htmlhelp.py
-  HTML help builder helper methods.
-
-_jinja.py, jinja
-  The Jinja templating engine, used for all HTML-related builders.
-
-refcounting.py
-  Helper to keep track of reference count data for the C API reference,
-  which is maintained as a separate file.
-
-roles.py
-  Role functions that transform our custom roles (like ``:meth:``) into doctree
-  nodes.
-
-search.py
-  Helper to create a search index for the offline search.
-
-style
-  Directory for all static files for HTML-related builders.
-
-templates
-  Directory for Jinja templates, ATM only for HTML.
-
-util
-  General utilities.
-
-writer.py
-  The docutils HTML writer subclass which understands our additional nodes.
-
-
-Code style
-----------
-
-PEP 8 (http://www.python.org/dev/peps/pep-0008) must be observed, with the
-following exceptions:
-
-* Line length is limited to 90 characters.
-* Relative imports are used, using with the new-in-2.5 'leading dot' syntax.
-
-The file encoding is UTF-8, this should be indicated in the file's first line
-with ::
-
-   # -*- coding: utf-8 -*-
-
-
-Python 3.0 compatibility
-------------------------
-
-As it will be used for Python 3.0 too, the toolset should be kept in a state
-where it is fully usable Python 3 code after one run of the ``2to3`` utility.

Deleted: /doctools/trunk/README
==============================================================================
--- /doctools/trunk/README	Sun Mar 16 14:06:12 2008
+++ (empty file)
@@ -1,103 +0,0 @@
-doctools README
-===============
-
-FIXME: This is already outdated since the conversion has happened and the
-reST sources are in the Python tree now.
-
-TODO: update this.
-
-
-What you need to know
----------------------
-
-This project uses Python 2.5 features, so you'll need a working Python
-2.5 setup.  Docutils 0.4 is required, the Docutils SVN trunk does not
-work at the moment, but I don't expect it to be difficult to fix that.
-
-Docutils can be installed from the PyPI (Cheese Shop) via ``easy_install``
-or from http://docutils.sourceforge.net/.
-
-If you want code highlighting, you need Pygments >= 0.8, easily
-installable from PyPI.  Jinja, the template engine, is included as a
-SVN external.
-
-
-Converting the LaTeX sources
-----------------------------
-
-**This paragraph is obsolete.**  The conversion has been done, and reST docs
-trees are now maintained for 2.6 and 3.0 branches.
-
-For the rest of this document, let's assume that you have a Python
-checkout (you need the 2.6 line, i.e. the trunk -- the SVN URL for readonly
-access is http://svn.python.org/projects/python/trunk) in ~/devel/python
-and this checkout in the current directory.
-
-To convert the LaTeX doc to reST, you first have to apply the patch in
-``etc/inst.diff`` to the ``inst/inst.tex`` LaTeX file in the Python
-checkout::
-
-   patch -d ~/devel/python/Doc -p0 < etc/inst.diff
-
-Then, create a target directory for the reST sources and run the
-converter script::
-
-   mkdir sources
-   python convert.py ~/devel/python/Doc sources
-
-This will convert all LaTeX sources to reST files in the ``sources``
-directory.
-
-The ``sources`` directory contains a ``conf.py`` file which contains
-general configuration for the build process, such as the Python
-version that should be shown, or the date format for "last updated on"
-notes.
-
-
-Building the HTML version
--------------------------
-
-Then, create a target directory and run ::
-
-   mkdir build-html
-   python sphinx-build.py -b html Doc-26 build-html
-
-This will create HTML files in the ``build-html`` directory.
-
-The ``build-html`` directory will also contain a ``.doctrees``
-directory, which caches pickles containing the docutils doctrees for
-all source files, as well as an ``environment.pickle`` file that
-collects all meta-information and data that's needed to
-cross-reference the sources and generate indices.
-
-
-Running the online (web) version
---------------------------------
-
-First, you need to build the source with the "web" builder::
-
-   mkdir build-web
-   python sphinx-build.py -b web Doc-26 build-web
-
-This will create files with pickled contents for the web application
-in the target directory.
-
-Then, you can run ::
-
-   python sphinx-web.py build-web
-
-which will start a webserver using wsgiref on ``localhost:3000``.  The
-web application has a configuration file ``build-web/webconf.py``,
-where you can configure the server and port for the application as
-well as different other settings specific to the web app.
-
-
-Writing new documentation
--------------------------
-
-The new "Documenting Python" document, contained in a converted documentation
-tree, already lists most of the markup and features, both standard reST and
-additional, that can be used in the source docs.
-
-More reST docs are at http://docutils.sf.net/rst.html, tutorials can be found on
-the web.
