annotate docs/README @ 5544:0bb75a6c29b1

rewind: add a --dry-run flag

There are 3 cases handled separately in formatstatus():

- common-case rewind when we have X current successors rewinding to Y
  predecessors

- rewinding with --as-divergence, when we don't obsolete current successors

- rewinding pruned commits, when we don't have current successors to show

In the common case, we might have sub-cases that change the output with
--dry-run (but not the way the rewind operates):

- more predecessors than successors (e.g. after a fold), in which case we
  simply use successorsmap, which maps successors to a set of predecessors

- equal number of predecessors and successors, see the previous case

- more successors than predecessors (e.g. after a split), in which case we
  use a reverse of successorsmap (rsm), which maps predecessors to a set of
  successors and exists only for the sake of --dry-run functionality

These two dicts allow us to group rewind targets and output separate lines for
separate predecessors<->successors relations.

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.