Mercurial > kallithea

annotate scripts/docs-headings.py @ 7811:0a277465fddf

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
scripts: initial run of import cleanup using isort
author Mads Kiilerich <mads@kiilerich.com>
date Wed, 07 Aug 2019 00:25:02 +0200
parents a188803df37e
children a8e6bb9ee9ea
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
7811
0a277465fddf scripts: initial run of import cleanup using isort
Mads Kiilerich <mads@kiilerich.com>
parents: 7499
diff changeset
10
5537
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
11 spaces = [
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
12 (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
13 (2, 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, 1),
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 (1, 0),
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
17 ]
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
18
5575
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
19 # http://sphinx-doc.org/rest.html :
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
20 # 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
21 # # with overline, for parts
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
22 # * with overline, for chapters
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
23 # =, for sections
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
24 # -, for subsections
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
25 # ^, for subsubsections
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
26 # ", for paragraphs
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
27 pystyles = ['#', '*', '=', '-', '^', '"']
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
28
5537
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
29 # 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
30 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
31
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
32
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
33 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
34 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
35 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
36 print 'processing %s' % fn
6860
665dfa112f2c py3: replace "file" with "open"
Lars Kruse <devel@sumpfralle.de>
parents: 5575
diff changeset
37 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
38
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
39 # 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
40 lastpos = 0
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
41 styles = []
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
42 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
43 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
44 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
45 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
46 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
47 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
48 else:
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
49 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
50 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
51 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
52 else:
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
53 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
54 lastpos = stylepos
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
55
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
56 # 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
57 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
58
5575
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
59 if styles:
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
60 newstyles = pystyles[pystyles.index(styles[0]):]
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
61
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
62 def subf(m):
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
63 title, style = m.groups()
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
64 level = styles.index(style)
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
65 before, after = spaces[level]
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
66 newstyle = newstyles[level]
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
67 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
68 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
69
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
70 # 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
71 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
72 # 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
73 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
74 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
75
6860
665dfa112f2c py3: replace "file" with "open"
Lars Kruse <devel@sumpfralle.de>
parents: 5575
diff changeset
76 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
77
a188803df37e scripts: docs-headings: improve performance by grouping 'hg diff' invocations
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 6860
diff changeset
78 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
79
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
80 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
81 main()