docs/tutorial/README.rst
author Pierre-Yves David <pierre-yves.david@octobus.net>
Wed, 25 Apr 2018 14:18:19 +0100
changeset 3726 116ef60d4be6
parent 3376 aad37ffd7d58
permissions -rw-r--r--
branching: merge with latest release
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
3376
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
     1
=============================
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
     2
Training supports
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
     3
=============================
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
     4
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
     5
Contributing
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
     6
============
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
     7
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
     8
The main source for the supports is the `slides.md` but it doesn't contains
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
     9
all the source.
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    10
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    11
The `slides.md` file contains several snippets that are replaced by other
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    12
files at compilation time.
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    13
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    14
For example:
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    15
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    16
.. code:: markdown
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    17
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    18
  ~~~raw-file
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    19
  output/fix-a-bug-base.log
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    20
  ~~~
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    21
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    22
Will replace this three lines by the content of the file `output/fix-a-bug-
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    23
base.log` which is generated when running the .t test file (see below for
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    24
instruction how to do that).
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    25
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    26
.. code:: markdown
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    27
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    28
  ~~~graphviz-file
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    29
  graphs/fix-bug-1.dot
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    30
  ~~~
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    31
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    32
Will replace this three lines by the svg rendering of the graphviz definition
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    33
in the file `graphs/fix-bug-1.dot`. This file is generated when running the .t
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    34
test file (see below for instruction how to do that).
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    35
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    36
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    37
Environment preparation
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    38
=======================
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    39
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    40
This training supports needs pandoc to compile.
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    41
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    42
You'll need a copy of the Mercurial source in order to generate the training
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    43
supports.
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    44
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    45
You will also needs a functioning Python environment with the possibility to
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    46
use `pip install` with your current user. In doubt, you can use a `virtualenv
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    47
<https://virtualenv.pypa.io/en/stable/>`.
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    48
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    49
You can then run the `prepare.sh` script that will configure the environment
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    50
for you.
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    51
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    52
Generating the supports
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    53
=======================
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    54
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    55
First, you need to run a .t test file to generate a bunch of files. You can
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    56
run the test file with this command:
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    57
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    58
`python /PATH/TO/MERCURIAL/tests/run-tests.py -l test-training.t`
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    59
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    60
It should have generated files in at least two directories: `graphs` and
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    61
`output`.
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    62
aad37ffd7d58 doc: import the training support
Boris Feld <boris.feld@octobus.net>
parents:
diff changeset
    63
Finally, launch the `compile.sh` to generate the `index.html` output file.