Move utils to separate package, add coding document.

HACKING

@@ -0,0 +1,140 @@
+.. -*- mode: rst -*-
+
+===============
+Coding overview
+===============
+
+This document tries to give you a cursory overview of the doctools code.
+
+
+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.

TODO

@@ -2,6 +2,7 @@ Global TODO
 ===========
 
 - discuss and debug comments system
+- navigation links at the bottom too
 - write new Makefile, handle automatic version info and checkout
 - write a "printable" builder (export to latex, most probably)
 - discuss the default role

sphinx/__init__.py

@@ -14,7 +14,7 @@ import getopt
 from os import path
 
 from .builder import builders
-from .console import nocolor
+from .util.console import nocolor
 
 __version__ = '$Revision: 5369 $'
 
@@ -99,6 +99,10 @@ def main(argv):
         elif opt == '-N':
             nocolor()
 
+    if sys.platform == 'win32':
+        # Windows' cmd box doesn't understand ANSI sequences
+        nocolor()
+
     if builder is None:
         print 'No builder selected, using default: html'
         builder = 'html'

sphinx/builder.py

@@ -29,7 +29,7 @@ from docutils.frontend import OptionParser
 from .util import (get_matching_files, attrdict, status_iterator,
                    ensuredir, get_category, relative_uri)
 from .writer import HTMLWriter
-from .console import bold, purple, green
+from .util.console import bold, purple, green
 from .htmlhelp import build_hhx
 from .environment import BuildEnvironment
 from .highlighting import pygments, get_stylesheet

sphinx/search.py

@@ -13,8 +13,8 @@ import pickle
 
 from collections import defaultdict
 from docutils.nodes import Text, NodeVisitor
-from .stemmer import PorterStemmer
-from .json import dump_json
+from .util.stemmer import PorterStemmer
+from .util.json import dump_json
 
 
 word_re = re.compile(r'\w+(?u)')

sphinx/util/console.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 """
-    sphinx.console
-    ~~~~~~~~~~~~~~
+    sphinx.util.console
+    ~~~~~~~~~~~~~~~~~~~
 
     Format colored console output.
 

sphinx/util/json.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 """
-    sphinx.json
-    ~~~~~~~~~~~
+    sphinx.util.json
+    ~~~~~~~~~~~~~~~~
 
     Minimal JSON module that generates small dumps.
 

sphinx/util/stemmer.py

@@ -1,8 +1,8 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 """
-    sphinx.stemmer
-    ~~~~~~~~~~~~~~
+    sphinx.util.stemmer
+    ~~~~~~~~~~~~~~~~~~~
 
     Porter Stemming Algorithm
 

sphinx/web/wsgiutil.py

@@ -24,7 +24,7 @@ from datetime import datetime
 from cStringIO import StringIO
 
 from .util import lazy_property
-from .json import dump_json
+from ..util.json import dump_json
 
 
 HTTP_STATUS_CODES = {

sphinx/writer.py

@@ -12,7 +12,7 @@
 from docutils import nodes
 from docutils.writers.html4css1 import Writer, HTMLTranslator as BaseTranslator
 
-from .smartypants import sphinx_smarty_pants
+from .util.smartypants import sphinx_smarty_pants
 
 
 class HTMLWriter(Writer):