Mercurial > kallithea
annotate scripts/docs-headings.py @ 6201:d55ff973d01f
lib: simplify version; drop get_current_revision - it was run every time on import time - we don't want that
This functionality was already not in use with the version numbers we use. I
also doubt it is possible to have version numbers where it worked - it seems
like there might have been some regression that nobody noticed. Dropping it
will thus not really lose any actual functionality.
If we want to include the revision number in the version (for browser cache
invalidation) then we should do it in a different way. Perhaps writing it to
some file from setup.py .
author | Mads Kiilerich <madski@unity3d.com> |
---|---|
date | Mon, 12 Sep 2016 17:41:19 +0200 |
parents | ed2fb6e84a02 |
children | 665dfa112f2c |
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(): |
f38b50f8a6a6
scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff
changeset
|
33 for fn in subprocess.check_output(['hg', 'loc', 'set:**.rst+kallithea/i18n/how_to']).splitlines(): |
f38b50f8a6a6
scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff
changeset
|
34 print 'processing %s:' % fn |
f38b50f8a6a6
scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff
changeset
|
35 s = file(fn).read() |
f38b50f8a6a6
scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff
changeset
|
36 |
f38b50f8a6a6
scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff
changeset
|
37 # 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
|
38 lastpos = 0 |
f38b50f8a6a6
scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff
changeset
|
39 styles = [] |
f38b50f8a6a6
scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff
changeset
|
40 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
|
41 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
|
42 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
|
43 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
|
44 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
|
45 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
|
46 else: |
f38b50f8a6a6
scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff
changeset
|
47 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
|
48 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
|
49 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
|
50 else: |
f38b50f8a6a6
scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff
changeset
|
51 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
|
52 lastpos = stylepos |
f38b50f8a6a6
scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff
changeset
|
53 |
f38b50f8a6a6
scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff
changeset
|
54 # 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
|
55 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
|
56 |
5575
ed2fb6e84a02
docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents:
5537
diff
changeset
|
57 if styles: |
ed2fb6e84a02
docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents:
5537
diff
changeset
|
58 newstyles = pystyles[pystyles.index(styles[0]):] |
ed2fb6e84a02
docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents:
5537
diff
changeset
|
59 |
ed2fb6e84a02
docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents:
5537
diff
changeset
|
60 def subf(m): |
ed2fb6e84a02
docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents:
5537
diff
changeset
|
61 title, style = m.groups() |
ed2fb6e84a02
docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents:
5537
diff
changeset
|
62 level = styles.index(style) |
ed2fb6e84a02
docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents:
5537
diff
changeset
|
63 before, after = spaces[level] |
ed2fb6e84a02
docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents:
5537
diff
changeset
|
64 newstyle = newstyles[level] |
ed2fb6e84a02
docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents:
5537
diff
changeset
|
65 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
|
66 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
|
67 |
f38b50f8a6a6
scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff
changeset
|
68 # 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
|
69 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
|
70 # 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
|
71 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
|
72 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
|
73 |
f38b50f8a6a6
scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff
changeset
|
74 file(fn, 'w').write(s) |
f38b50f8a6a6
scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff
changeset
|
75 print subprocess.check_output(['hg', 'diff', fn]) |
f38b50f8a6a6
scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff
changeset
|
76 print |
f38b50f8a6a6
scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff
changeset
|
77 |
f38b50f8a6a6
scripts: introduce scripts/docs-headings.py for reformatting rst section titles in docs
Mads Kiilerich <madski@unity3d.com>
parents:
diff
changeset
|
78 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
|
79 main() |