IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Remove obsolete documents.

Browse Source
This commit is contained in:
Georg Brandl
2008-03-16 13:06:12 +00:00
parent b1fbe7a2b6
commit 8affe87531
2 changed files with 0 additions and 245 deletions
Download Patch File Download Diff File Expand all files Collapse all files

142
HACKING
View 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.

103
README
View 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.