annotate docs/README @ 3237:9a2cc4687cb9

cache: introduce an abstract class for cache we can upgrade incrementally

Right now each class implements their own mechanism for validation, and
update. We start introducing abstract class to ultimately allow more
unification of the cache code.

The end goal of this series is to introduce a cache for some obsolescence
property, not to actually implement the cache. However, taking advantage of
adding a new cache to introduce the abstract class seems like a win.

This code was headed for core during the 4.3 cycle but never made it there. So
we starts with a copy in the evolve repository.

Doc is generated with sphinx.

You can generate the doc with:

```
make
```

# Tutorials

For updating the tutorials, you need to have the docgraph extension installed
(https://pypi.python.org/pypi/hg-docgraph).

Then run the test-topic-tutorial.t and test-tutorial.t to update the output if
needed.

You'll need the dot binary (likely installed by the graphviz package in your
package manager) in order to have graphviz graphs rendered in the html output.

Simply run make in the docs directory should takes care of the conversion of
the tutorial .t files into .rst files. Then sphinx should do the rest of the
jobs by rendering graphviz graphs.