Code review comment for lp:~ian-clatworthy/bzr/doc-site-per-language

Martin Pool wrote:
> My only real concern is the copy & paste of the version number.

Yes, that's ugly.

> Does this add a new hard dependency on anything? If so, we should be careful of the impact on distributions and packagers.

Sphinx 0.6.x. I guess packagers could pull the generated html docs from
our download area if that's a problem?

The patch currently builds both html and PDF by default. It's probably
better to tweak that to be just the html as the PDF generation requires
a lot of LaTeX-related dependencies.

> 1547 +
> 1548 +# We *could* get this from bzrlib but there's no certainly that the bzr on
> 1549 +# the Python path is indeed the one we're building the documentation for ...
> 1550 +bzr_version = (2, 0, 0, 'rc', 2)
> 1551 +
> 1552 +
>
> urk, you're right that just 'import bzrlib' will be problematic, but this is almost certainly going to become incorrect. If from the Makefile you do "PYTHONPATH=.:$PYTHONPATH" then future loads of bzrlib should see the right thing.

I'd be happy enough to sort this out post shipping rc2. I'm
expecting/hoping to make some *minor* doc tweaks (e.g. fix some
cross-document links) and streamlining the version lookup could come as
part of that patch if you agree?

We need to tweak multiple Makefiles for all 4+ of them to pick up the
right version number. I guess there's some simple, risk-free way of
doing this, but I wasn't inspired at the time to work it out. (We have
various Makefiles are different levels btw.)

> +release = version + ''.join(str(p) for p in bzr_version[3:])
>
> Could you import and use _format_version_tuple?

Probably.

> +http://doc.bazaar-vcs.org/developers/.
>
> Put it in angle brackets so the . isn't part of the url? (I guess it's harmless.)

I assume that's a ReST-ism?

> 2079 Bazaar Developer Document Catalog
> 2080 =================================
> 2081
> 2082 -
> 2083 -Overall developer documentation
> 2084 -===============================
> 2085 -
> 2086 -* `Developer Guide <../en/developer-guide/HACKING.html>`_
> 2087 -
> 2088 -* `Architectural Overview <overview.html>`_ |--| describes some of the
> 2089 - most important classes and concepts.
> 2090 +.. toctree::
> 2091 + :hidden:
> 2092 +
> 2093 + process
> 2094 + HACKING
> 2095 + testing
> 2096 + overview
> 2097 + integration
> 2098 + plans
> 2099 + specifications
> 2100 + implementation-notes
> 2101 + miscellaneous-notes
> 2102 +
> 2103 +
> 2104 +Core developer documentation
>
> What does this do?

It:

1. ensures next and previous topic links work
2. provides checking that all files are in the topic tree somewhere
3. probably provides some other magic I can't remember (or don't know).

> Could sphinx help us get away from manually maintaining indexes of documentation?

It can build a readable TOC from the toctree directive by taking the
titles out of each doc, yes. It can also do some true index stuff but
I'm yet to look into that.

Ian C.