Mercurial > kallithea

annotate scripts/docs-headings.py @ 7673:642847355a10

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
hooks: make sure push and pull hooks always are enabled Don't put things in the database when we pretty much assume they always have exact content, without any reasonable use case for customization.
author Mads Kiilerich <mads@kiilerich.com>
date Wed, 23 Jan 2019 03:52:13 +0100
parents a188803df37e
children 0a277465fddf
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5537
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
1 #!/usr/bin/env python2
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
2
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
3 """
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
4 Consistent formatting of rst section titles
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
5 """
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
6
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
7 import re
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
8 import subprocess
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
9
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
10 spaces = [
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
11 (0, 1), # we assume this is a over-and-underlined header
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
12 (2, 1),
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
13 (1, 1),
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
14 (1, 0),
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
15 (1, 0),
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
16 ]
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
17
5575
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
18 # http://sphinx-doc.org/rest.html :
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
19 # for the Python documentation, this convention is used which you may follow:
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
20 # # with overline, for parts
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
21 # * with overline, for chapters
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
22 # =, for sections
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
23 # -, for subsections
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
24 # ^, for subsubsections
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
25 # ", for paragraphs
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
26 pystyles = ['#', '*', '=', '-', '^', '"']
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
27
5537
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
28 # match on a header line underlined with one of the valid characters
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
29 headermatch = re.compile(r'''\n*(.+)\n([][!"#$%&'()*+,./:;<=>?@\\^_`{|}~-])\2{2,}\n+''', flags=re.MULTILINE)
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
30
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
31
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
32 def main():
7499
a188803df37e scripts: docs-headings: improve performance by grouping 'hg diff' invocations
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 6860
diff changeset
33 filenames = subprocess.check_output(['hg', 'loc', 'set:**.rst+kallithea/i18n/how_to']).splitlines()
a188803df37e scripts: docs-headings: improve performance by grouping 'hg diff' invocations
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 6860
diff changeset
34 for fn in filenames:
a188803df37e scripts: docs-headings: improve performance by grouping 'hg diff' invocations
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 6860
diff changeset
35 print 'processing %s' % fn
6860
665dfa112f2c py3: replace "file" with "open"
Lars Kruse <devel@sumpfralle.de>
parents: 5575
diff changeset
36 s = open(fn).read()
5537
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
37
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
38 # find levels and their styles
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
39 lastpos = 0
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
40 styles = []
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
41 for markup in headermatch.findall(s):
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
42 style = markup[1]
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
43 if style in styles:
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
44 stylepos = styles.index(style)
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
45 if stylepos > lastpos + 1:
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
46 print 'bad style %r with level %s - was at %s' % (style, stylepos, lastpos)
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
47 else:
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
48 stylepos = len(styles)
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
49 if stylepos > lastpos + 1:
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
50 print 'bad new style %r - expected %r' % (style, styles[lastpos + 1])
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
51 else:
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
52 styles.append(style)
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
53 lastpos = stylepos
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
54
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
55 # remove superfluous spacing (may however be restored by header spacing)
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
56 s = re.sub(r'''(\n\n)\n*''', r'\1', s, flags=re.MULTILINE)
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
57
5575
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
58 if styles:
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
59 newstyles = pystyles[pystyles.index(styles[0]):]
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
60
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
61 def subf(m):
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
62 title, style = m.groups()
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
63 level = styles.index(style)
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
64 before, after = spaces[level]
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
65 newstyle = newstyles[level]
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
66 return '\n' * (before + 1) + title + '\n' + newstyle * len(title) + '\n' * (after + 1)
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
67 s = headermatch.sub(subf, s)
5537
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
68
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
69 # remove superfluous spacing when headers are adjacent
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
70 s = re.sub(r'''(\n.+\n([][!"#$%&'()*+,./:;<=>?@\\^_`{|}~-])\2{2,}\n\n\n)\n*''', r'\1', s, flags=re.MULTILINE)
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
71 # fix trailing space and spacing before link sections
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
72 s = s.strip() + '\n'
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
73 s = re.sub(r'''\n+((?:\.\. _[^\n]*\n)+)$''', r'\n\n\n\1', s)
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
74
6860
665dfa112f2c py3: replace "file" with "open"
Lars Kruse <devel@sumpfralle.de>
parents: 5575
diff changeset
75 open(fn, 'w').write(s)
7499
a188803df37e scripts: docs-headings: improve performance by grouping 'hg diff' invocations
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 6860
diff changeset
76
a188803df37e scripts: docs-headings: improve performance by grouping 'hg diff' invocations
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 6860
diff changeset
77 print subprocess.check_output(['hg', 'diff'] + filenames)
5537
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
78
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
79 if __name__ == '__main__':
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
80 main()