[RFC] more agressive error check for `make docs`?

Ian Clatworthy ian.clatworthy at internode.on.net
Wed Sep 5 03:20:23 BST 2007

Alexander Belchenko wrote:
> Currently `make docs` always runs successful even if there is
> some warnings or errors during html generation. I think it's bad,
> because periodically I find regressions.


> But at first we need to fix 'see also' in help for send command.

The send command may be the most obvious problem (because it's breaking
ReST generation) but the issue is broader than that. For example, the
global-options topic references doc/developers/profiling.txt which is
equally undesirable.

I looked at this earlier this week and didn't see an easy answer to
suggest. As you've raised the topic though, here's a short brain dump to
add to the discussion ...

One approach is to treat documentation as a "layered architecture":

* reference material (WHAT) is the lowest layer and can only
  cross-reference itself

* other material (usually HOW) can reference "down" to the WHAT material
  or "across" to sister docs.

While this sort of things works well in large code bases, I don't think
it delivers the best quality doc overall. Sometimes you really do want
to cross-reference HOW material from WHAT material and the answer isn't
"improve the WHAT material so it's more useful stand-alone".

So that means we need some way of cleanly cross-referencing docs - and
topics within docs - from online help and from each other. Referencing
filenames isn't the right way IMO. After all, there's no top level "doc"
directory in the doc put up on http://doc.bazaar-vcs.org and the .txt
extension is an obvious bad smell.

As mentioned above, I don't have a solution. Part of the problem is that
we don't want docutils - the ReST toolkit - to be a runtime dependency.
Embedding true ReST links in the online help topics will make those less
readable. Perhaps we need to do that though and either:

* make the existing 'mini-ReST -> natural text converter' nicer
* add docutils as a dependency
* bundle some docutil code in with bzr (licensing permitted)

Another option is to use smart heuristics in the conversion processes.
In that case the doc/xxx/yyy.txt could be used as a conversion hint and
our rst2html.py script and friends would add custom magic.

Yet another option is to have a scheme like "document:topic" and to
support that across online help as well. In other words, make User Guide
topics available from the online help system. Note that this doesn't
necessarily mean display them as text. Perhaps it would be acceptable for

  bzr help guide:configuration

to launch your Web Browser and put up the relevant page on
http://doc.bazaar-vcs.org? That has the advantage of making things like
the Quick Reference cards available as legal cross references.

Thoughts and suggestion welcome, both for short term fixes and long term

Ian C.

More information about the bazaar mailing list