docs/test2rst.py
author Boris Feld <boris.feld@octobus.net>
Thu, 21 Sep 2017 10:45:27 +0200
changeset 2959 ef361938dfa1
parent 2958 1cb715257130
child 2960 1a4f26eec0af
permissions -rw-r--r--
doc: integrate graphviz graphs in tutorials Use the mercurial-docgraph extension (https://pypi.python.org/pypi/hg- docgraph/) in tutorials in order to have some dot graphs in the tutorials .t files. Then generate the doc as usual, the sphinx-graphviz extension (http://www .sphinx-doc.org/en/stable/ext/graphviz.html) has been added and it should handle the generation of the graphs. Please be aware that you need the dot binary installed in your system. Please refer to the extension documentation for more configuration.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
235
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
     1
#!/usr/bin/env python
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
     2
2035
94fe2cc9cd41 flake8: fix error in 'test2rst.py'
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 525
diff changeset
     3
import os
94fe2cc9cd41 flake8: fix error in 'test2rst.py'
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 525
diff changeset
     4
import os.path as op
94fe2cc9cd41 flake8: fix error in 'test2rst.py'
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 525
diff changeset
     5
import sys
235
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
     6
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
     7
INDEX = '''
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
     8
Mercurial tests
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
     9
===============
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    10
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    11
.. toctree::
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    12
   :maxdepth: 1
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    13
'''
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    14
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    15
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    16
def rstify(orig, name):
2825
7608f1e04205 doc: fix test2rst
Boris Feld <boris.feld@octobus.net>
parents: 2035
diff changeset
    17
    newlines = []
7608f1e04205 doc: fix test2rst
Boris Feld <boris.feld@octobus.net>
parents: 2035
diff changeset
    18
7608f1e04205 doc: fix test2rst
Boris Feld <boris.feld@octobus.net>
parents: 2035
diff changeset
    19
    code_block_mode = False
2959
ef361938dfa1 doc: integrate graphviz graphs in tutorials
Boris Feld <boris.feld@octobus.net>
parents: 2958
diff changeset
    20
    sphinx_directive_mode = False
2825
7608f1e04205 doc: fix test2rst
Boris Feld <boris.feld@octobus.net>
parents: 2035
diff changeset
    21
7608f1e04205 doc: fix test2rst
Boris Feld <boris.feld@octobus.net>
parents: 2035
diff changeset
    22
    for line in orig.splitlines():
7608f1e04205 doc: fix test2rst
Boris Feld <boris.feld@octobus.net>
parents: 2035
diff changeset
    23
7608f1e04205 doc: fix test2rst
Boris Feld <boris.feld@octobus.net>
parents: 2035
diff changeset
    24
        # Emtpy lines doesn't change output
7608f1e04205 doc: fix test2rst
Boris Feld <boris.feld@octobus.net>
parents: 2035
diff changeset
    25
        if not line:
7608f1e04205 doc: fix test2rst
Boris Feld <boris.feld@octobus.net>
parents: 2035
diff changeset
    26
            newlines.append(line)
2959
ef361938dfa1 doc: integrate graphviz graphs in tutorials
Boris Feld <boris.feld@octobus.net>
parents: 2958
diff changeset
    27
            code_block_mode = False
ef361938dfa1 doc: integrate graphviz graphs in tutorials
Boris Feld <boris.feld@octobus.net>
parents: 2958
diff changeset
    28
            sphinx_directive_mode = False
ef361938dfa1 doc: integrate graphviz graphs in tutorials
Boris Feld <boris.feld@octobus.net>
parents: 2958
diff changeset
    29
            continue
2958
1cb715257130 doc: add a special flag for content to ignore in the rst
Boris Feld <boris.feld@octobus.net>
parents: 2951
diff changeset
    30
1cb715257130 doc: add a special flag for content to ignore in the rst
Boris Feld <boris.feld@octobus.net>
parents: 2951
diff changeset
    31
        # Ignore line
1cb715257130 doc: add a special flag for content to ignore in the rst
Boris Feld <boris.feld@octobus.net>
parents: 2951
diff changeset
    32
        if line.endswith('#rest-ignore'):
2825
7608f1e04205 doc: fix test2rst
Boris Feld <boris.feld@octobus.net>
parents: 2035
diff changeset
    33
            continue
7608f1e04205 doc: fix test2rst
Boris Feld <boris.feld@octobus.net>
parents: 2035
diff changeset
    34
2959
ef361938dfa1 doc: integrate graphviz graphs in tutorials
Boris Feld <boris.feld@octobus.net>
parents: 2958
diff changeset
    35
        # Sphinx directives mode
ef361938dfa1 doc: integrate graphviz graphs in tutorials
Boris Feld <boris.feld@octobus.net>
parents: 2958
diff changeset
    36
        if line.startswith('  .. '):
ef361938dfa1 doc: integrate graphviz graphs in tutorials
Boris Feld <boris.feld@octobus.net>
parents: 2958
diff changeset
    37
ef361938dfa1 doc: integrate graphviz graphs in tutorials
Boris Feld <boris.feld@octobus.net>
parents: 2958
diff changeset
    38
            # Insert a empty line to makes sphinx happy
ef361938dfa1 doc: integrate graphviz graphs in tutorials
Boris Feld <boris.feld@octobus.net>
parents: 2958
diff changeset
    39
            newlines.append("")
ef361938dfa1 doc: integrate graphviz graphs in tutorials
Boris Feld <boris.feld@octobus.net>
parents: 2958
diff changeset
    40
ef361938dfa1 doc: integrate graphviz graphs in tutorials
Boris Feld <boris.feld@octobus.net>
parents: 2958
diff changeset
    41
            # And unindent the directive
ef361938dfa1 doc: integrate graphviz graphs in tutorials
Boris Feld <boris.feld@octobus.net>
parents: 2958
diff changeset
    42
            line = line[2:]
ef361938dfa1 doc: integrate graphviz graphs in tutorials
Boris Feld <boris.feld@octobus.net>
parents: 2958
diff changeset
    43
            sphinx_directive_mode = True
ef361938dfa1 doc: integrate graphviz graphs in tutorials
Boris Feld <boris.feld@octobus.net>
parents: 2958
diff changeset
    44
ef361938dfa1 doc: integrate graphviz graphs in tutorials
Boris Feld <boris.feld@octobus.net>
parents: 2958
diff changeset
    45
        # Code mode
2825
7608f1e04205 doc: fix test2rst
Boris Feld <boris.feld@octobus.net>
parents: 2035
diff changeset
    46
        codeline = line.startswith('  ')
2959
ef361938dfa1 doc: integrate graphviz graphs in tutorials
Boris Feld <boris.feld@octobus.net>
parents: 2958
diff changeset
    47
        if codeline and not sphinx_directive_mode:
2825
7608f1e04205 doc: fix test2rst
Boris Feld <boris.feld@octobus.net>
parents: 2035
diff changeset
    48
            if code_block_mode is False:
7608f1e04205 doc: fix test2rst
Boris Feld <boris.feld@octobus.net>
parents: 2035
diff changeset
    49
                newlines.extend(['::', ''])
7608f1e04205 doc: fix test2rst
Boris Feld <boris.feld@octobus.net>
parents: 2035
diff changeset
    50
7608f1e04205 doc: fix test2rst
Boris Feld <boris.feld@octobus.net>
parents: 2035
diff changeset
    51
            code_block_mode = True
7608f1e04205 doc: fix test2rst
Boris Feld <boris.feld@octobus.net>
parents: 2035
diff changeset
    52
7608f1e04205 doc: fix test2rst
Boris Feld <boris.feld@octobus.net>
parents: 2035
diff changeset
    53
        newlines.append(line)
7608f1e04205 doc: fix test2rst
Boris Feld <boris.feld@octobus.net>
parents: 2035
diff changeset
    54
7608f1e04205 doc: fix test2rst
Boris Feld <boris.feld@octobus.net>
parents: 2035
diff changeset
    55
    return "\n".join(newlines)
235
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    56
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    57
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    58
def main(base):
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    59
    if os.path.isdir(base):
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    60
        one_dir(base)
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    61
    else:
525
a0327c78a5d3 doc: remove spurious print in test2rest.py
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 235
diff changeset
    62
        one_file(base)
235
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    63
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    64
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    65
def one_dir(base):
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    66
    index = INDEX
2035
94fe2cc9cd41 flake8: fix error in 'test2rst.py'
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 525
diff changeset
    67
    # doc = lambda x: op.join(op.dirname(__file__), 'docs', x)
235
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    68
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    69
    for fn in sorted(os.listdir(base)):
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    70
        if not fn.endswith('.t'):
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    71
            continue
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    72
        name = os.path.splitext(fn)[0]
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    73
        content = one_file(op.join(base, fn))
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    74
        target = op.join(base, name + '.rst')
2035
94fe2cc9cd41 flake8: fix error in 'test2rst.py'
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 525
diff changeset
    75
        # with file(doc(name + '.rst'), 'w') as f:
94fe2cc9cd41 flake8: fix error in 'test2rst.py'
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 525
diff changeset
    76
        with open(target, 'w') as f:
235
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    77
            f.write(content)
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    78
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    79
        index += '\n   ' + name
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    80
2035
94fe2cc9cd41 flake8: fix error in 'test2rst.py'
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 525
diff changeset
    81
    # with file(doc('index.rst'), 'w') as f:
94fe2cc9cd41 flake8: fix error in 'test2rst.py'
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 525
diff changeset
    82
    #     f.write(index)
235
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    83
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    84
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    85
def one_file(path):
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    86
    name = os.path.basename(path)[:-2]
2035
94fe2cc9cd41 flake8: fix error in 'test2rst.py'
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 525
diff changeset
    87
    return rstify(open(path).read(), name)
235
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    88
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    89
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    90
if __name__ == '__main__':
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    91
    if len(sys.argv) != 2:
2035
94fe2cc9cd41 flake8: fix error in 'test2rst.py'
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 525
diff changeset
    92
        print('Please supply a path to tests dir as parameter')
235
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    93
        sys.exit()
8469ccb9550f [doc] add `.t` to `.rst` converteur
Pierre-Yves.David@ens-lyon.org
parents:
diff changeset
    94
    main(sys.argv[1])