Skip to content

Commit d5e5216

Browse files
Mic92Mic92
committed
various documentation generation fixes
1 parent 00377e7 commit d5e5216

File tree

2 files changed

+685
-428
lines changed

2 files changed

+685
-428
lines changed

‎doc/generate_command_reference.py

+97-63
Original file line numberDiff line numberDiff line change
@@ -1,81 +1,115 @@
11
#!/usr/bin/env python
22

3-
import re, sys
3+
import re
4+
import sys
45
import os.path
6+
from textwrap import TextWrapper
57
try:
68
from lxml import etree
79
except ImportError:
810
sys.stderr.write("Please install lxml to run this script.")
911
sys.exit(1)
1012

11-
url = "http://git.musicpd.org/cgit/cirrus/mpd.git/plain/doc/protocol.xml"
13+
DEPRECATED_COMMANDS = ["volume"]
14+
SCRIPT_PATH = os.path.dirname(os.path.realpath(__file__))
1215

13-
if len(sys.argv) > 1:
14-
url += "?id=release-" + sys.argv[1]
1516

16-
DIR = os.path.dirname(os.path.realpath(__file__))
17-
header_file = os.path.join(DIR, "commands_header.txt")
17+
def get_text(elements, itemize=False):
18+
paragraphs = []
19+
highlight_elements = ['varname', 'parameter']
20+
strip_elements = [
21+
'returnvalue',
22+
'command',
23+
'link',
24+
'footnote',
25+
'simpara',
26+
'footnoteref',
27+
'function'
28+
] + highlight_elements
29+
for element in elements:
30+
# put "Since MPD version..." in paranthese
31+
etree.strip_tags(element, "application")
32+
for e in element.xpath("footnote/simpara"):
33+
e.text = "(" + e.text.strip() + ")"
1834

19-
DEPRECATED_COMMANDS = ["volume"]
35+
for e in element.xpath("|".join(highlight_elements)):
36+
e.text = "*" + e.text.strip() + "*"
37+
etree.strip_tags(element, *strip_elements)
38+
if itemize:
39+
initial_indent = " * "
40+
subsequent_indent = " "
41+
else:
42+
initial_indent = " "
43+
subsequent_indent = " "
44+
wrapper = TextWrapper(subsequent_indent=subsequent_indent,
45+
initial_indent=initial_indent)
46+
text = element.text.replace("\n", " ").strip()
47+
text = re.subn(r'\s+', ' ', text)[0]
48+
paragraphs.append(wrapper.fill(text))
49+
return "\n\n".join(paragraphs)
2050

21-
with open(header_file, 'r') as f:
22-
print(f.read())
2351

24-
tree = etree.parse(url)
25-
chapter = tree.xpath('/book/chapter/title[text()= "Command reference"]/..')[0]
26-
for section in chapter.xpath("section"):
27-
title = section.xpath("title")[0].text
28-
print(title)
29-
print(len(title) * "-")
52+
def main(url):
53+
header_file = os.path.join(SCRIPT_PATH, "commands_header.txt")
54+
with open(header_file, 'r') as f:
55+
print(f.read())
3056

31-
paragraphs = []
32-
for paragraph in section.xpath("para"):
33-
etree.strip_tags(paragraph, 'varname', 'command', 'parameter')
34-
text = paragraph.text.rstrip()
35-
paragraphs.append(text)
36-
print("\n".join(paragraphs))
37-
print("")
57+
tree = etree.parse(url)
58+
chapter = tree.xpath('/book/chapter[@id="command_reference"]')[0]
59+
for section in chapter.xpath("section"):
60+
title = section.xpath("title")[0].text
61+
print(title)
62+
print(len(title) * "-")
63+
64+
print(get_text(section.xpath("para")))
65+
print("")
66+
67+
for entry in section.xpath("variablelist/varlistentry"):
68+
cmd = entry.xpath("term/cmdsynopsis/command")[0].text
69+
if cmd in DEPRECATED_COMMANDS:
70+
continue
71+
subcommand = ""
72+
args = ""
73+
begin_optional = False
74+
first_argument = True
75+
76+
for arg in entry.xpath("term/cmdsynopsis/arg"):
77+
choice = arg.attrib.get("choice", None)
78+
if choice == "opt" and not begin_optional:
79+
begin_optional = True
80+
args += "["
81+
if args != "" and args != "[":
82+
args += ", "
83+
replaceables = arg.xpath("replaceable")
84+
if len(replaceables) > 0:
85+
for replaceable in replaceables:
86+
args += replaceable.text.lower()
87+
elif first_argument:
88+
subcommand = arg.text
89+
else:
90+
args += '"{}"'.format(arg.text)
91+
first_argument = False
92+
if begin_optional:
93+
args += "]"
94+
if subcommand != "":
95+
cmd += "_" + subcommand
96+
print(".. function:: MPDClient." + cmd + "(" + args + ")")
97+
description = get_text(entry.xpath("listitem/para"))
98+
description = re.sub(r':$', r'::', description, flags=re.MULTILINE)
3899

39-
for entry in section.xpath("variablelist/varlistentry"):
40-
cmd = entry.xpath("term/cmdsynopsis/command")[0].text
41-
if cmd in DEPRECATED_COMMANDS:
42-
continue
43-
subcommand = ""
44-
args = ""
45-
begin_optional = False
46-
first_argument = True
100+
print("\n")
101+
print(description)
102+
print("\n")
47103

48-
for arg in entry.xpath("term/cmdsynopsis/arg"):
49-
choice = arg.attrib.get("choice", None)
50-
if choice == "opt" and not begin_optional:
51-
begin_optional = True
52-
args += "["
53-
if args != "" and args != "[":
54-
args += ", "
55-
replaceables = arg.xpath("replaceable")
56-
if len(replaceables) > 0:
57-
for replaceable in replaceables:
58-
args += replaceable.text.lower()
59-
elif first_argument:
60-
subcommand = arg.text
61-
else:
62-
args += '"{}"'.format(arg.text)
63-
first_argument = False
64-
if begin_optional:
65-
args += "]"
66-
if subcommand != "":
67-
cmd += "_" + subcommand
68-
print(".. function:: MPDClient." + cmd + "(" + args + ")")
69-
lines = []
70-
for para in entry.xpath("listitem/para"):
71-
etree.strip_tags(para, 'varname', 'command', 'parameter')
72-
t = [t.rstrip() for t in para.xpath("text()")]
73-
lines.append(" ".join(t))
74-
description = "\n".join(lines)
75-
description = re.sub(r':$',r'::', description,flags=re.MULTILINE)
104+
for screen in entry.xpath("listitem/screen | listitem/programlisting"):
105+
for line in screen.text.split("\n"):
106+
print(" " + line)
107+
for item in entry.xpath("listitem/itemizedlist/listitem"):
108+
print(get_text(item.xpath("para"), itemize=True))
109+
print("\n")
76110

77-
print(description)
78-
print("\n")
79-
for screen in entry.xpath("listitem/screen | listitem/programlisting"):
80-
for line in screen.text.split("\n"):
81-
print(" " + line)
111+
if __name__ == "__main__":
112+
url = "http://git.musicpd.org/cgit/cirrus/mpd.git/plain/doc/protocol.xml"
113+
if len(sys.argv) > 1:
114+
url += "?id=release-" + sys.argv[1]
115+
main(url)

0 commit comments

Comments
 (0)