Mercurial > kallithea

annotate scripts/docs-headings.py @ 8209:01aca0a4f876

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
py3: officially support Python 3 All tests pass and no known regressions.
author Mads Kiilerich <mads@kiilerich.com>
date Wed, 05 Feb 2020 22:28:20 +0100
parents aa6f17a53b49
children 4b68fbe195b6
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8173
aa6f17a53b49 py3: switch to use Python 3 interpreter, temporarily leaving many things very broken until they have been migrated/fixed in a reviewable way
Mads Kiilerich <mads@kiilerich.com>
parents: 7844
diff changeset
1 #!/usr/bin/env python3
5537
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
7844
a8e6bb9ee9ea future: use Python print function
Mads Kiilerich <mads@kiilerich.com>
parents: 7811
diff changeset
7 from __future__ import print_function
a8e6bb9ee9ea future: use Python print function
Mads Kiilerich <mads@kiilerich.com>
parents: 7811
diff changeset
8
5537
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
9 import re
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
10 import subprocess
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
11
7811
0a277465fddf scripts: initial run of import cleanup using isort
Mads Kiilerich <mads@kiilerich.com>
parents: 7499
diff changeset
12
5537
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
13 spaces = [
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
14 (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
15 (2, 1),
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
16 (1, 1),
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
17 (1, 0),
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
18 (1, 0),
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
19 ]
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
20
5575
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
21 # http://sphinx-doc.org/rest.html :
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
22 # 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
23 # # with overline, for parts
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
24 # * with overline, for chapters
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
25 # =, for sections
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
26 # -, for subsections
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
27 # ^, for subsubsections
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
28 # ", for paragraphs
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
29 pystyles = ['#', '*', '=', '-', '^', '"']
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
30
5537
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
31 # 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
32 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
33
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
34
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
35 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
36 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
37 for fn in filenames:
8209
01aca0a4f876 py3: officially support Python 3
Mads Kiilerich <mads@kiilerich.com>
parents: 8173
diff changeset
38 fn = fn.decode()
7844
a8e6bb9ee9ea future: use Python print function
Mads Kiilerich <mads@kiilerich.com>
parents: 7811
diff changeset
39 print('processing %s' % fn)
6860
665dfa112f2c py3: replace "file" with "open"
Lars Kruse <devel@sumpfralle.de>
parents: 5575
diff changeset
40 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
41
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
42 # 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
43 lastpos = 0
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
44 styles = []
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
45 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
46 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
47 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
48 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
49 if stylepos > lastpos + 1:
7844
a8e6bb9ee9ea future: use Python print function
Mads Kiilerich <mads@kiilerich.com>
parents: 7811
diff changeset
50 print('bad style %r with level %s - was at %s' % (style, stylepos, lastpos))
5537
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 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
53 if stylepos > lastpos + 1:
7844
a8e6bb9ee9ea future: use Python print function
Mads Kiilerich <mads@kiilerich.com>
parents: 7811
diff changeset
54 print('bad new style %r - expected %r' % (style, styles[lastpos + 1]))
5537
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
55 else:
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
56 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
57 lastpos = stylepos
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
58
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
59 # 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
60 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
61
5575
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
62 if styles:
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
63 newstyles = pystyles[pystyles.index(styles[0]):]
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
64
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
65 def subf(m):
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
66 title, style = m.groups()
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
67 level = styles.index(style)
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
68 before, after = spaces[level]
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
69 newstyle = newstyles[level]
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5537
diff changeset
70 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
71 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
72
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
73 # 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
74 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
75 # 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
76 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
77 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
78
6860
665dfa112f2c py3: replace "file" with "open"
Lars Kruse <devel@sumpfralle.de>
parents: 5575
diff changeset
79 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
80
7844
a8e6bb9ee9ea future: use Python print function
Mads Kiilerich <mads@kiilerich.com>
parents: 7811
diff changeset
81 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
82
f38b50f8a6a6 scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
83 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
84 main()