Merge lp:~tseaver/loggerhead/sphinxify into lp:loggerhead

[Tres Seaver]

Add Sphinx-based documentation to the source tree.

[lp:~tseaver/loggerhead/sphinxify]

403. By Tres Seaver <email address hidden> on 2010-03-23

ReST fixups, better cross-references.

404. By Tres Seaver <email address hidden> on 2010-03-23

Explain plugin usage, link bazaar-webserve and hgweb.

405. By Tres Seaver <email address hidden> on 2010-03-23

Move cross-ref of bazaar-webserve and hgweb to intro graph; remove dead modindex and search.

406. By Tres Seaver <email address hidden> on 2010-03-23

Better section title.

[Matt Nordhoff (mnordhoff)]

Some small comments on part of it (I'm watching TV now...):

> 317 +oggerhead is heavily based on `bazaar-webserve

Missing an L in "Loggerhead". ;-)

> 331 +- Paste for the server. (You need version 1.2 or newer of Paste.)
> 332 +
> 333 +- Paste Deploy (optional, needed when proxying through Apache)
> 334 +
> 335 +- flup (optional, needed to use FastCGI, SCGI or AJP)

The style is rather inconsistent here -- the spacing and "(foo)" vs. "(Foo.)".

Also, what should be done with the README now?

[Matt Nordhoff (mnordhoff)]

A couple spots use "loggerhead"; I'd prefer "Loggerhead". Not a big deal, though.

> 730 + Setting this option keeps loggerhead from adding a 'readonly+' prefix
> 731 + to the base URL of is to make visible the display of instructions for
> 732 + checking out the 'public_branch' URL for the branch being browsed.

That...what? "base URL of is to make"?

If it ever includes "readonly+" in URL in the example instructions, that's a bug. Aside from that, --allow-writes isn't really related to the instructions; it's about how the server itself works.

> 810 + Override configuration file location [XXX default is
> 811 + :file:`/etc/loggerhead.conf`]

> 815 + The directory [XXX in which] to place log files

XXX comments?

Mostly this sounds really cool. Thank you. :-)

If someone who has Sphinx installed can confirm that the syntax isn't horribly wrong or something (or maybe I'll do it myself later), I'd be happy to land it, once these (minor) issues are fixed. Even if it isn't perfect, it's certainly an improvement over Loggerhead's current documentation situation. "Don't let the perfect be the enemy of the good" and all.

bb:tweak

review: Needs Fixing

[lp:~tseaver/loggerhead/sphinxify]

407. By Tres Seaver <email address hidden> on 2010-03-23

Better section title.

408. By Tres Seaver <email address hidden> on 2010-03-25

Use 'Loggerhead' as the display name; fix typos.

409. By Tres Seaver <email address hidden> on 2010-03-25

Consistent punctuation.

[Tres Seaver (tseaver)]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Matt Nordhoff wrote:
> Some small comments on part of it (I'm watching TV now...):
>
>> 317 +oggerhead is heavily based on `bazaar-webserve
>
> Missing an L in "Loggerhead". ;-)

Fixed in r408 of my branch.

>> 331 +- Paste for the server. (You need version 1.2 or newer of Paste.)
>> 332 +
>> 333 +- Paste Deploy (optional, needed when proxying through Apache)
>> 334 +
>> 335 +- flup (optional, needed to use FastCGI, SCGI or AJP)
>
> The style is rather inconsistent here -- the spacing and "(foo)" vs. "(Foo.)".

Fixed in r409 of my branch.

> Also, what should be done with the README now?

Most projects I know using Sphinx remove the bulk of the information
from the README, leaving behind a pointer to the Sphinx docs. I wasn't
sure how you would want to handle that: I can push a changeset with a
suggested diff for the README if you like.

Tres.
- --
===================================================================
Tres Seaver [phone] <email address hidden>
Palladion Software "Excellence by Design" http://palladion.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkurO1QACgkQ+gerLs4ltQ4TFACgtiYb2dawlxWfHOIoV2LlZEsr
xXIAoJDYXKUt8jhVbHxqbTP703fHrrz2
=W3GW
-----END PGP SIGNATURE-----

[lp:~tseaver/loggerhead/sphinxify]

410. By Tres Seaver <email address hidden> on 2010-03-25

Try to clarify my reverse-engineered explanation of --allow-writes semantics.

411. By Tres Seaver <email address hidden> on 2010-03-25

Consistent punctuation, capitalization; remove XXX.

[Tres Seaver (tseaver)]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Matt Nordhoff wrote:
> Review: Needs Fixing
> A couple spots use "loggerhead"; I'd prefer "Loggerhead". Not a big deal, though.

Fix included in r408 of my branch.

>> 730 + Setting this option keeps loggerhead from adding a 'readonly+' prefix
>> 731 + to the base URL of is to make visible the display of instructions for
>> 732 + checking out the 'public_branch' URL for the branch being browsed.
>
> That...what? "base URL of is to make"?

Sorry for the typo. r410 tries to clarify.

> If it ever includes "readonly+" in URL in the example instructions,
> that's a bug. Aside from that, --allow-writes isn't really related to
> the instructions; it's about how the server itself works.

I was trying to document what effect the option actualy has, by
spelunking the code. From my exploration, it appears that the option
has a somewhat misleading name: it doesn't appear to make the
Loggerhead server willing to accept any changes from clients (in fact,
in my experience, I have to serve a "raw" bzr tree from another URL to
allow even a checkout).

At any rate, I might be completely wrong about the intended (or actual)
semantics. I do know that passing '--allow-writes' on the command line
was the only way I found to get the branch UI to show the block of HTML
which gives directions for checking out the branch.

>> 810 + Override configuration file location [XXX default is
>> 811 + :file:`/etc/loggerhead.conf`]
>
>> 815 + The directory [XXX in which] to place log files
>
> XXX comments?

Fossils from my efforts to reverse engineer from the manpage source: I
have elided them in r411.

> Mostly this sounds really cool. Thank you. :-)
>
> If someone who has Sphinx installed can confirm that the syntax isn't
> horribly wrong or something (or maybe I'll do it myself later), I'd be
> happy to land it, once these (minor) issues are fixed. Even if it isn't
> perfect, it's certainly an improvement over Loggerhead's current
> documentation situation. "Don't let the perfect be the enemy of the
> good" and all.

I'm glad it helps. Sphinx has been a big win for us on the repoze project.

Tres.
- --
===================================================================
Tres Seaver [phone] <email address hidden>
Palladion Software "Excellence by Design" http://palladion.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkurPtoACgkQ+gerLs4ltQ5uvgCdHGEM+TBqNvhQEqAkWP3fiylt
wtMAoJoqpzsBBvt/JuZWmgMJMUkoKl0P
=gvDH
-----END PGP SIGNATURE-----

[Matt Nordhoff (mnordhoff)]

Tres Seaver wrote:
> I was trying to document what effect the option actualy has, by
> spelunking the code. From my exploration, it appears that the option
> has a somewhat misleading name: it doesn't appear to make the
> Loggerhead server willing to accept any changes from clients (in fact,
> in my experience, I have to serve a "raw" bzr tree from another URL to
> allow even a checkout).
>
> At any rate, I might be completely wrong about the intended (or actual)
> semantics. I do know that passing '--allow-writes' on the command line
> was the only way I found to get the branch UI to show the block of HTML
> which gives directions for checking out the branch.

--allow-writes is supposed to simply allow pushing to the smart server,
and have no impact on the "bzr branch" example.

This wouldn't be the first time it's gotten broken, though...

The "bzr branch" example should always be displayed, unless you're
serving a remote location (e.g. "serve-branches bzr+ssh://...") and the
branch has no public_branch setting. Hmm, looking at the code, I may
have already spotted an issue, though.
--
Matt Nordhoff

[Matt Nordhoff (mnordhoff)]

Matt Nordhoff wrote:
> --allow-writes is supposed to simply allow pushing to the smart server,
> and have no impact on the "bzr branch" example.

I meant to add that that makes it equivalent to "bzr serve
--allow-writes", which makes it extremely dangerous. Without some sort
of auth setup, and if Loggerhead's user has write access to the
directory tree you're serving, anyone can use bzrlib to screw with it.
--
Matt Nordhoff

[Matt Nordhoff (mnordhoff)]

There should be NEWS, too. :D (Which can be added by whoever lands this.)

[Matt Nordhoff (mnordhoff)]

Matt Nordhoff wrote:
> Tres Seaver wrote:
> > I was trying to document what effect the option actualy has, by
> > spelunking the code. From my exploration, it appears that the option
> > has a somewhat misleading name: it doesn't appear to make the
> > Loggerhead server willing to accept any changes from clients (in fact,
> > in my experience, I have to serve a "raw" bzr tree from another URL to
> > allow even a checkout).
> >
> > At any rate, I might be completely wrong about the intended (or actual)
> > semantics. I do know that passing '--allow-writes' on the command line
> > was the only way I found to get the branch UI to show the block of HTML
> > which gives directions for checking out the branch.
>
> --allow-writes is supposed to simply allow pushing to the smart server,
> and have no impact on the "bzr branch" example.
>
> This wouldn't be the first time it's gotten broken, though...
>
> The "bzr branch" example should always be displayed, unless you're
> serving a remote location (e.g. "serve-branches bzr+ssh://...") and the
> branch has no public_branch setting. Hmm, looking at the code, I may
> have already spotted an issue, though.

Following up on this, I sent a merge proposal to fix the "To get this branch" bit, and I tested --allow-writes and it's working as expected.

[Tres Seaver (tseaver)]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Matt Nordhoff wrote:
> Matt Nordhoff wrote:
>> Tres Seaver wrote:
>>> I was trying to document what effect the option actualy has, by
>>> spelunking the code. From my exploration, it appears that the option
>>> has a somewhat misleading name: it doesn't appear to make the
>>> Loggerhead server willing to accept any changes from clients (in fact,
>>> in my experience, I have to serve a "raw" bzr tree from another URL to
>>> allow even a checkout).
>>>
>>> At any rate, I might be completely wrong about the intended (or actual)
>>> semantics. I do know that passing '--allow-writes' on the command line
>>> was the only way I found to get the branch UI to show the block of HTML
>>> which gives directions for checking out the branch.
>> --allow-writes is supposed to simply allow pushing to the smart server,
>> and have no impact on the "bzr branch" example.
>>
>> This wouldn't be the first time it's gotten broken, though...
>>
>> The "bzr branch" example should always be displayed, unless you're
>> serving a remote location (e.g. "serve-branches bzr+ssh://...") and the
>> branch has no public_branch setting. Hmm, looking at the code, I may
>> have already spotted an issue, though.
>
> Following up on this, I sent a merge proposal to fix the "To get this
> branch" bit, and I tested --allow-writes and it's working as
> expected.

I was able to test your branch:

  lp:~mnordhoff/loggerhead/readonly_local_path_from_url/

and the fix for showing branchinfo HTML is working with '--allow-writes'
turned off for me. Upgrading to that branch made the "local" checkouts
work again, too (I had been running on the 1.17.0 release of loggerhead).

Tres.
- --
===================================================================
Tres Seaver [phone] <email address hidden>
Palladion Software "Excellence by Design" http://palladion.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkurl88ACgkQ+gerLs4ltQ7v2QCgm1mXOu9wf7qjab6TNU5u+Yyn
HDEAoMy8jbGvT8b2TZZAVA+Ibg+iDixp
=f3oV
-----END PGP SIGNATURE-----

[Ian Clatworthy (ian-clatworthy)]

Tres,

This is awesome - thanks. I'll add a NEWS entry and merge.

A question: why multiple lines in .bzrignore, as opposed to just adding ./build/?

review: Approve

[Ian Clatworthy (ian-clatworthy)]

This is merged now. I made some very minor tweaks to index.rst, updated the README and added a NEWS item while merging. If there are any problems with my tweaks, please let me know.

[Tres Seaver (tseaver)]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Ian Clatworthy wrote:

> This is awesome - thanks. I'll add a NEWS entry and merge.

Great!

> A question: why multiple lines in .bzrignore, as opposed to just adding ./build/?

Maybe my bzr-fu isn't strong enough: at least with a Subversion
project, you want the 'docs/_build' directory to be in the repository
(because the Makefile won't create it), but want to ignore anything
which is created inside it by the build process. The two lines could
probably just be 'docs/_build/*'. Or did the existing 'build' entry
already prevent anything from being noticed in that directory?

Tres.
- --
===================================================================
Tres Seaver [phone] <email address hidden>
Palladion Software "Excellence by Design" http://palladion.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkvEeVQACgkQ+gerLs4ltQ5qogCgmHuwMhCwy2g09GcITpWVzj/p
ESYAoMzUkala/ODJcB4lXmKCvhrDq2d7
=jHmY
-----END PGP SIGNATURE-----

[Ian Clatworthy (ian-clatworthy)]

On 14/04/10 00:03, Tres Seaver wrote:

> The two lines could
> probably just be 'docs/_build/*'.

Yes. Or ./docs/_build/

I've simplified it accordingly.

> Or did the existing 'build' entry
> already prevent anything from being noticed in that directory?

No, the existing build entry will mask out ./build/ or docs/build/ but
not docs/_build.

Ian C.

=== modified file '.bzrignore'
--- .bzrignore	2009-04-01 14:40:05 +0000
+++ .bzrignore	2010-03-25 10:44:29 +0000
@@ -7,3 +7,5 @@
 *.log
 _trial_temp
 loggerhead-memprofile
+docs/_build/doctrees
+docs/_build/html

=== added directory 'docs'
=== added file 'docs/Makefile'
--- docs/Makefile	1970-01-01 00:00:00 +0000
+++ docs/Makefile	2010-03-25 10:44:29 +0000
@@ -0,0 +1,89 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html      to make standalone HTML files"
+	@echo "  dirhtml   to make HTML files named index.html in directories"
+	@echo "  pickle    to make pickle files"
+	@echo "  json      to make JSON files"
+	@echo "  htmlhelp  to make HTML files and a HTML help project"
+	@echo "  qthelp    to make HTML files and a qthelp project"
+	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  changes   to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck to check all external links for integrity"
+	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/loggerhead.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/loggerhead.qhc"
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+	      "run these through (pdf)latex."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."

=== added directory 'docs/_build'
=== added directory 'docs/_static'
=== added directory 'docs/_templates'
=== added file 'docs/conf.py'
--- docs/conf.py	1970-01-01 00:00:00 +0000
+++ docs/conf.py	2010-03-25 10:44:29 +0000
@@ -0,0 +1,194 @@
+# -*- coding: utf-8 -*-
+#
+# loggerhead documentation build configuration file, created by
+# sphinx-quickstart on Tue Mar 23 10:49:50 2010.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.append(os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Loggerhead'
+copyright = u'2010, Loggerhead team (https://launchpad.net/~loggerhead-team)'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '1.17'
+# The full version, including alpha/beta/rc tags.
+release = '1.17'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directory, that shouldn't be searched
+# for source files.
+exclude_trees = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'loggerheaddoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'loggerhead.tex', u'Loggerhead Documentation',
+   u'Loggerhead team (https://launchpad.net/\\textasciitilde{}loggerhead-team)', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True

=== added file 'docs/index.rst'
--- docs/index.rst	1970-01-01 00:00:00 +0000
+++ docs/index.rst	2010-03-25 10:44:29 +0000
@@ -0,0 +1,211 @@
+Loggerhead:  A web viewer for ``bzr`` branches
+==============================================
+
+Loggerhead is a web viewer for projects in bazaar. It can be used to navigate 
+a branch history, annotate files, view patches, perform searches, etc.
+Loggerhead is heavily based on `bazaar-webserve
+<https://launchpad.net/bzr-webserve>`_, which was, in turn, loosely
+based on `hgweb <http://mercurial.selenic.com/wiki/HgWebDirStepByStep>`_.
+
+
+Getting Started
+---------------
+
+Loggerhead depends on the following Python libraries.:
+
+- SimpleTAL for templating.
+
+- simplejson for producing JSON data.
+
+- Paste for the server. (You need version 1.2 or newer of Paste).
+
+- Paste Deploy  (optional, needed when proxying through Apache).
+
+- flup (optional, needed to use FastCGI, SCGI or AJP).
+
+
+Installing Dependencies Using Ubuntu Packages
+#############################################
+
+.. code-block:: sh
+
+   $ sudo apt-get install python-simpletal
+   $ sudo apt-get install python-simplejson
+   $ sudo apt-get install python-paste
+   $ sudo apt-get install python-pastedeploy
+   $ sudo apt-get install python-flup
+
+Installing Dependencies Using :command:`easy_install`
+#####################################################
+
+.. code-block:: sh
+
+   $ easy_install \
+     -f http://www.owlfish.com/software/simpleTAL/py2compatible/download.html \
+     SimpleTAL
+   $ easy_install simplejson
+   $ easy_install Paste
+   $ easy_install PasteDeploy
+   $ easy_install flup
+
+
+Running the Standalone Loggerhead Server
+----------------------------------------
+
+After installing all the dependencies, you should be able to run
+:command:`serve-branches` with the branch you want to serve on the
+command line:
+
+.. code-block:: sh
+
+    ./serve-branches ~/path/to/branch
+
+By default, the script listens on port 8080, so head to
+http://localhost:8080/ in your browser to see the branch.
+
+You can also pass a directory that contains branches to the script,
+and it will serve a very simple directory listing at other pages.
+
+You may update the Bazaar branches being viewed at any time.
+Loggerhead will notice and refresh, and Bazaar uses its own branch
+locking to prevent corruption.
+
+See :doc:`serve-branches` for all command line options.
+
+Running Loggerhead as a Daemon
+------------------------------
+
+To run Loggerhead as a linux daemon:
+
+1) Copy the ``loggerheadd`` scipt to ``/etc/init.d``
+
+.. code-block:: sh
+
+   $ sudo cp ./loggerheadd /etc/init.d
+
+2) Edit the file to configure where your Loggerhead is installed, and which
+   serve-branches options you would like.
+
+.. code-block:: sh
+
+   $ sudo vim /etc/init.d/loggerheadd
+
+3) Register the service
+
+.. code-block:: sh
+
+   # on upstart based systems like Ubuntu run: 
+   $ sudo update-rc.d loggerheadd defaults
+
+   # on Sysvinit based systems like Centos or SuSE run:
+   $ sudo chkconfig --add loggerheadd
+
+
+Using Loggerhead as a Bazaar Plugin
+------------------------------------
+
+This branch contains experimental support for using Loggerhead as a Bazaar
+plugin.  To use it, place the top-level Loggerhead directory (the one
+containing this file) at ``~/.bazaar/plugins/loggerhead``.  E.g.:
+
+.. code-block:: sh
+
+   $ bzr branch lp:loggerhead ~/.bazaar/plugins/loggerhead
+   $ cd ~/myproject
+   $ bzr serve --http
+
+
+Using a Config File
+-------------------
+
+To hide branches from being displayed, add to ``~/.bazaar/locations.conf``,
+under the branch's section:
+
+.. code-block:: ini
+
+    [/path/to/branch]
+    http_serve = False
+
+More configuration options to come soon.
+
+
+Serving Loggerhead behind Apache
+--------------------------------
+
+If you want to view Bazaar branches from your existing Apache
+installation, you'll need to configure Apache to proxy certain
+requests to Loggerhead.  Adding lines like this to you Apache
+configuration is one way to do this:
+
+.. code-block:: apache
+
+    <Location "/branches/">
+        ProxyPass http://127.0.0.1:8080/branches/
+        ProxyPassReverse http://127.0.0.1:8080/branches/
+    </Location>
+
+If Paste Deploy is installed, the :command:`serve-branches` script can be
+run behind a proxy at the root of a site, but if you're running it at
+some path into the site, you'll need to specify is using
+``--prefix=/some_path``.
+
+
+Search
+------
+
+Search is currently supported by using the bzr-search plugin (available
+at: https://launchpad.net/bzr-search ).
+
+You need to have the plugin installed and each branch indexed to allow
+searching on branches.
+
+Command-Line Reference
+----------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   serve-branches
+   start-loggerhead
+   stop-loggerhead
+
+
+Support
+-------
+
+Discussion should take place on the bazaar-dev mailing list at
+mailto:[e-mail].  You can join the list at
+<https://lists.ubuntu.com/mailman/listinfo/bazaar>.  You don't need to
+subscribe to post, but your first post will be held briefly for manual
+moderation.
+
+Bugs are tracked on Launchpad; start at:
+
+    https://bugs.launchpad.net/loggerhead
+
+
+Hacking
+-------
+
+To run Loggerhead tests, you will need to install the package ``python-nose``,
+and run its :command:`nosetests` script in the Loggerhead directory:
+
+.. code-block:: sh
+
+    nosetests
+
+
+License
+-------
+
+GNU GPLv2 or later.
+
+See Also
+--------
+
+https://launchpad.net/loggerhead
+
+Index
+=====
+
+- :ref:`genindex`

=== added file 'docs/make.bat'
--- docs/make.bat	1970-01-01 00:00:00 +0000
+++ docs/make.bat	2010-03-25 10:44:29 +0000
@@ -0,0 +1,113 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+set SPHINXBUILD=sphinx-build
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	:help
+	echo.Please use `make ^<target^>` where ^<target^> is one of
+	echo.  html      to make standalone HTML files
+	echo.  dirhtml   to make HTML files named index.html in directories
+	echo.  pickle    to make pickle files
+	echo.  json      to make JSON files
+	echo.  htmlhelp  to make HTML files and a HTML help project
+	echo.  qthelp    to make HTML files and a qthelp project
+	echo.  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  changes   to make an overview over all changed/added/deprecated items
+	echo.  linkcheck to check all external links for integrity
+	echo.  doctest   to run all doctests embedded in the documentation if enabled
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
+	goto end
+)
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	echo.
+	echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\loggerhead.qhcp
+	echo.To view the help file:
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\loggerhead.ghc
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	echo.
+	echo.The overview file is in %BUILDDIR%/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+	goto end
+)
+
+:end

=== added file 'docs/serve-branches.rst'
--- docs/serve-branches.rst	1970-01-01 00:00:00 +0000
+++ docs/serve-branches.rst	2010-03-25 10:44:29 +0000
@@ -0,0 +1,116 @@
+:command:`serve-branches`
+=========================
+
+The :command:`serve-branches` script runs a standalone Loggerhead server in
+the foreground.
+
+.. program:: serve-branches
+
+Usage
+-----
+
+.. code-block:: sh
+
+   serve-branches [OPTIONS] <target directory>
+
+Options
+-------
+
+.. cmdoption:: --user-dirs
+
+    Serve user directories as ``~user`` (requires ``--trunk-dir``).
+
+    If both options are set, then for requests where the CGI ``PATH_INFO``
+    starts with "/~<name>", serve branches under the <name> directory.
+
+.. cmdoption:: --trunk-dir=DIR
+
+    The directory that contains the trunk branches (requires ``--user-dirs``).
+
+    If both options are set, then for requests where the CGI ``PATH_INFO``
+    does not start with "/~<name>", serve branches under DIR.
+
+.. cmdoption:: --port
+
+    Listen on the given port.
+    
+    Defaults to 8080.
+
+.. cmdoption:: --host
+
+    Listen on the interface corresponding to the given IP. 
+    
+    Defaults to listening on all interfaces, i.e., "0.0.0.0".
+
+.. cmdoption:: --protocol
+
+    Serve the application using the specified protocol.
+    
+    Can be one of: "http", "scgi", "fcgi", "ajp" (defaults to "http").
+
+.. cmdoption:: --prefix
+
+    Set the supplied value as the CGI ``SCRIPT_NAME`` for the application.
+
+    This option is intended for use when serving Loggerhead behind a
+    reverse proxy, with Loggerhead being "mounted" at a directory below
+    the root.  E.g., if the reverse proxy translates requests for
+    ``http://example.com/loggerhead`` onto the standalone Loggerhead process,
+    that process should be run with ``--prefix=/loggerhead``.
+
+.. cmdoption:: --log-folder=LOG_FOLDER
+
+    The directory in which to place Loggerhead's log files.
+    
+    Defaults to the current directory.
+
+.. cmdoption:: --cache-dir=SQL_CACHE_DIR
+
+    The directory in which to place the SQL cache.
+
+    Defaults to the current directory.
+
+.. cmdoption:: --use-cdn
+   
+    Serve YUI javascript libraries from Yahoo!'s CDN.
+
+.. cmdoption:: --allow-writes
+   
+    Allow writing to the Bazaar server.
+    
+    Setting this option keeps Loggerhead from adding a 'readonly+' prefix
+    to the base URL of the branch.  The only effect of suppressing this prefix
+    is to make visible the display of instructions for checking out the
+    'public_branch' URL for the branch being browsed.
+
+.. cmdoption:: -h, --help
+
+    Print the help message and exit
+
+.. cmdoption:: --version
+
+    Print the software version and exit.
+
+Debugging Options
+-----------------
+
+The following options are only useful when developing / debugging Loggerhead
+itself.
+
+.. cmdoption:: --profile
+   
+    Generate per-request callgrind profile data.
+    
+    Data for each request is written to a file ``%d-stats.callgrind``,
+    where ``%d`` is replaced by the sequence number of the request.
+
+.. cmdoption:: --memory-profile
+
+    Profile the memory usage using the `Dozer
+    <http://pypi.python.org/pypi/Dozer>`_ middleware.
+
+.. cmdoption:: --reload
+
+    Restart the application when any of its python file change.
+    
+    This option should only used for development purposes.

=== added file 'docs/start-loggerhead.rst'
--- docs/start-loggerhead.rst	1970-01-01 00:00:00 +0000
+++ docs/start-loggerhead.rst	2010-03-25 10:44:29 +0000
@@ -0,0 +1,46 @@
+:command:`start-loggerhead`
+===========================
+
+The :command:`start-loggerhead` command starts a new standalone Loggerhead
+server.  By default, the server runs in the background (daemonized).
+
+.. program:: start-loggerhead
+
+Usage
+-----
+
+.. code-block:: sh
+
+    start-loggerhead [OPTIONS]
+
+Options
+-------
+
+.. cmdoption:: --version
+
+    Print the software version and exit.
+
+.. cmdoption:: -h, --help
+
+    Show this help message and exit.
+
+.. cmdoption:: --foreground
+
+    Run in the foreground;  don't daemonize.
+
+.. cmdoption:: -C, --check
+
+    Only start if not already running (useful for cron jobs).
+
+.. cmdoption:: -p, --pidfile=PIDFILE
+
+    Override pid file location.
+
+.. cmdoption:: -c, --config-file=CONFIGFILE
+
+    Override configuration file location (the default is
+    :file:`/etc/loggerhead.conf`).
+
+.. cmdoption:: --log-folder=LOG_FOLDER
+
+    The directory in which to place log files.

=== added file 'docs/stop-loggerhead.rst'
--- docs/stop-loggerhead.rst	1970-01-01 00:00:00 +0000
+++ docs/stop-loggerhead.rst	2010-03-25 10:44:29 +0000
@@ -0,0 +1,18 @@
+:command:`stop-loggerhead`
+======================================================================
+
+The :command:`stop-loggerhead` command stops the currently running Loggerhead
+daemon.
+
+.. program:: stop-loggerhead
+
+Usage
+-----
+
+.. code-block:: sh
+
+   stop-loggerhead [OPTIONS]
+
+.. cmdoption:: -p, --pidfile=PIDFILE
+
+   override pid file location