bitdoc 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533
  1. #!/usr/bin/env python3
  2. # ex:ts=4:sw=4:sts=4:et
  3. # -*- tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*-
  4. #
  5. # Copyright (C) 2005 Holger Hans Peter Freyther
  6. #
  7. # SPDX-License-Identifier: GPL-2.0-only
  8. #
  9. # This program is free software; you can redistribute it and/or modify
  10. # it under the terms of the GNU General Public License version 2 as
  11. # published by the Free Software Foundation.
  12. #
  13. # This program is distributed in the hope that it will be useful,
  14. # but WITHOUT ANY WARRANTY; without even the implied warranty of
  15. # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  16. # GNU General Public License for more details.
  17. #
  18. # You should have received a copy of the GNU General Public License along
  19. # with this program; if not, write to the Free Software Foundation, Inc.,
  20. # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  21. import optparse, os, sys
  22. # bitbake
  23. sys.path.append(os.path.join(os.path.dirname(os.path.dirname(__file__), 'lib'))
  24. import bb
  25. import bb.parse
  26. from string import split, join
  27. __version__ = "0.0.2"
  28. class HTMLFormatter:
  29. """
  30. Simple class to help to generate some sort of HTML files. It is
  31. quite inferior solution compared to docbook, gtkdoc, doxygen but it
  32. should work for now.
  33. We've a global introduction site (index.html) and then one site for
  34. the list of keys (alphabetical sorted) and one for the list of groups,
  35. one site for each key with links to the relations and groups.
  36. index.html
  37. all_keys.html
  38. all_groups.html
  39. groupNAME.html
  40. keyNAME.html
  41. """
  42. def replace(self, text, *pairs):
  43. """
  44. From pydoc... almost identical at least
  45. """
  46. while pairs:
  47. (a, b) = pairs[0]
  48. text = join(split(text, a), b)
  49. pairs = pairs[1:]
  50. return text
  51. def escape(self, text):
  52. """
  53. Escape string to be conform HTML
  54. """
  55. return self.replace(text,
  56. ('&', '&'),
  57. ('<', '&lt;' ),
  58. ('>', '&gt;' ) )
  59. def createNavigator(self):
  60. """
  61. Create the navgiator
  62. """
  63. return """<table class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  64. <tr valign="middle">
  65. <td><a accesskey="g" href="index.html">Home</a></td>
  66. <td><a accesskey="n" href="all_groups.html">Groups</a></td>
  67. <td><a accesskey="u" href="all_keys.html">Keys</a></td>
  68. </tr></table>
  69. """
  70. def relatedKeys(self, item):
  71. """
  72. Create HTML to link to foreign keys
  73. """
  74. if len(item.related()) == 0:
  75. return ""
  76. txt = "<p><b>See also:</b><br>"
  77. txts = []
  78. for it in item.related():
  79. txts.append("""<a href="key%(it)s.html">%(it)s</a>""" % vars() )
  80. return txt + ",".join(txts)
  81. def groups(self, item):
  82. """
  83. Create HTML to link to related groups
  84. """
  85. if len(item.groups()) == 0:
  86. return ""
  87. txt = "<p><b>See also:</b><br>"
  88. txts = []
  89. for group in item.groups():
  90. txts.append( """<a href="group%s.html">%s</a> """ % (group, group) )
  91. return txt + ",".join(txts)
  92. def createKeySite(self, item):
  93. """
  94. Create a site for a key. It contains the header/navigator, a heading,
  95. the description, links to related keys and to the groups.
  96. """
  97. return """<!doctype html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
  98. <html><head><title>Key %s</title></head>
  99. <link rel="stylesheet" href="style.css" type="text/css">
  100. <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  101. %s
  102. <h2><span class="refentrytitle">%s</span></h2>
  103. <div class="refsynopsisdiv">
  104. <h2>Synopsis</h2>
  105. <p>
  106. %s
  107. </p>
  108. </div>
  109. <div class="refsynopsisdiv">
  110. <h2>Related Keys</h2>
  111. <p>
  112. %s
  113. </p>
  114. </div>
  115. <div class="refsynopsisdiv">
  116. <h2>Groups</h2>
  117. <p>
  118. %s
  119. </p>
  120. </div>
  121. </body>
  122. """ % (item.name(), self.createNavigator(), item.name(),
  123. self.escape(item.description()), self.relatedKeys(item), self.groups(item))
  124. def createGroupsSite(self, doc):
  125. """
  126. Create the Group Overview site
  127. """
  128. groups = ""
  129. sorted_groups = sorted(doc.groups())
  130. for group in sorted_groups:
  131. groups += """<a href="group%s.html">%s</a><br>""" % (group, group)
  132. return """<!doctype html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
  133. <html><head><title>Group overview</title></head>
  134. <link rel="stylesheet" href="style.css" type="text/css">
  135. <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  136. %s
  137. <h2>Available Groups</h2>
  138. %s
  139. </body>
  140. """ % (self.createNavigator(), groups)
  141. def createIndex(self):
  142. """
  143. Create the index file
  144. """
  145. return """<!doctype html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
  146. <html><head><title>Bitbake Documentation</title></head>
  147. <link rel="stylesheet" href="style.css" type="text/css">
  148. <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  149. %s
  150. <h2>Documentation Entrance</h2>
  151. <a href="all_groups.html">All available groups</a><br>
  152. <a href="all_keys.html">All available keys</a><br>
  153. </body>
  154. """ % self.createNavigator()
  155. def createKeysSite(self, doc):
  156. """
  157. Create Overview of all avilable keys
  158. """
  159. keys = ""
  160. sorted_keys = sorted(doc.doc_keys())
  161. for key in sorted_keys:
  162. keys += """<a href="key%s.html">%s</a><br>""" % (key, key)
  163. return """<!doctype html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
  164. <html><head><title>Key overview</title></head>
  165. <link rel="stylesheet" href="style.css" type="text/css">
  166. <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  167. %s
  168. <h2>Available Keys</h2>
  169. %s
  170. </body>
  171. """ % (self.createNavigator(), keys)
  172. def createGroupSite(self, gr, items, _description = None):
  173. """
  174. Create a site for a group:
  175. Group the name of the group, items contain the name of the keys
  176. inside this group
  177. """
  178. groups = ""
  179. description = ""
  180. # create a section with the group descriptions
  181. if _description:
  182. description += "<h2 Description of Grozp %s</h2>" % gr
  183. description += _description
  184. items.sort(lambda x, y:cmp(x.name(), y.name()))
  185. for group in items:
  186. groups += """<a href="key%s.html">%s</a><br>""" % (group.name(), group.name())
  187. return """<!doctype html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
  188. <html><head><title>Group %s</title></head>
  189. <link rel="stylesheet" href="style.css" type="text/css">
  190. <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  191. %s
  192. %s
  193. <div class="refsynopsisdiv">
  194. <h2>Keys in Group %s</h2>
  195. <pre class="synopsis">
  196. %s
  197. </pre>
  198. </div>
  199. </body>
  200. """ % (gr, self.createNavigator(), description, gr, groups)
  201. def createCSS(self):
  202. """
  203. Create the CSS file
  204. """
  205. return """.synopsis, .classsynopsis
  206. {
  207. background: #eeeeee;
  208. border: solid 1px #aaaaaa;
  209. padding: 0.5em;
  210. }
  211. .programlisting
  212. {
  213. background: #eeeeff;
  214. border: solid 1px #aaaaff;
  215. padding: 0.5em;
  216. }
  217. .variablelist
  218. {
  219. padding: 4px;
  220. margin-left: 3em;
  221. }
  222. .variablelist td:first-child
  223. {
  224. vertical-align: top;
  225. }
  226. table.navigation
  227. {
  228. background: #ffeeee;
  229. border: solid 1px #ffaaaa;
  230. margin-top: 0.5em;
  231. margin-bottom: 0.5em;
  232. }
  233. .navigation a
  234. {
  235. color: #770000;
  236. }
  237. .navigation a:visited
  238. {
  239. color: #550000;
  240. }
  241. .navigation .title
  242. {
  243. font-size: 200%;
  244. }
  245. div.refnamediv
  246. {
  247. margin-top: 2em;
  248. }
  249. div.gallery-float
  250. {
  251. float: left;
  252. padding: 10px;
  253. }
  254. div.gallery-float img
  255. {
  256. border-style: none;
  257. }
  258. div.gallery-spacer
  259. {
  260. clear: both;
  261. }
  262. a
  263. {
  264. text-decoration: none;
  265. }
  266. a:hover
  267. {
  268. text-decoration: underline;
  269. color: #FF0000;
  270. }
  271. """
  272. class DocumentationItem:
  273. """
  274. A class to hold information about a configuration
  275. item. It contains the key name, description, a list of related names,
  276. and the group this item is contained in.
  277. """
  278. def __init__(self):
  279. self._groups = []
  280. self._related = []
  281. self._name = ""
  282. self._desc = ""
  283. def groups(self):
  284. return self._groups
  285. def name(self):
  286. return self._name
  287. def description(self):
  288. return self._desc
  289. def related(self):
  290. return self._related
  291. def setName(self, name):
  292. self._name = name
  293. def setDescription(self, desc):
  294. self._desc = desc
  295. def addGroup(self, group):
  296. self._groups.append(group)
  297. def addRelation(self, relation):
  298. self._related.append(relation)
  299. def sort(self):
  300. self._related.sort()
  301. self._groups.sort()
  302. class Documentation:
  303. """
  304. Holds the documentation... with mappings from key to items...
  305. """
  306. def __init__(self):
  307. self.__keys = {}
  308. self.__groups = {}
  309. def insert_doc_item(self, item):
  310. """
  311. Insert the Doc Item into the internal list
  312. of representation
  313. """
  314. item.sort()
  315. self.__keys[item.name()] = item
  316. for group in item.groups():
  317. if not group in self.__groups:
  318. self.__groups[group] = []
  319. self.__groups[group].append(item)
  320. self.__groups[group].sort()
  321. def doc_item(self, key):
  322. """
  323. Return the DocumentationInstance describing the key
  324. """
  325. try:
  326. return self.__keys[key]
  327. except KeyError:
  328. return None
  329. def doc_keys(self):
  330. """
  331. Return the documented KEYS (names)
  332. """
  333. return self.__keys.keys()
  334. def groups(self):
  335. """
  336. Return the names of available groups
  337. """
  338. return self.__groups.keys()
  339. def group_content(self, group_name):
  340. """
  341. Return a list of keys/names that are in a specefic
  342. group or the empty list
  343. """
  344. try:
  345. return self.__groups[group_name]
  346. except KeyError:
  347. return []
  348. def parse_cmdline(args):
  349. """
  350. Parse the CMD line and return the result as a n-tuple
  351. """
  352. parser = optparse.OptionParser( version = "Bitbake Documentation Tool Core version %s, %%prog version %s" % (bb.__version__, __version__))
  353. usage = """%prog [options]
  354. Create a set of html pages (documentation) for a bitbake.conf....
  355. """
  356. # Add the needed options
  357. parser.add_option( "-c", "--config", help = "Use the specified configuration file as source",
  358. action = "store", dest = "config", default = os.path.join("conf", "documentation.conf") )
  359. parser.add_option( "-o", "--output", help = "Output directory for html files",
  360. action = "store", dest = "output", default = "html/" )
  361. parser.add_option( "-D", "--debug", help = "Increase the debug level",
  362. action = "count", dest = "debug", default = 0 )
  363. parser.add_option( "-v", "--verbose", help = "output more chit-char to the terminal",
  364. action = "store_true", dest = "verbose", default = False )
  365. options, args = parser.parse_args( sys.argv )
  366. bb.msg.init_msgconfig(options.verbose, options.debug)
  367. return options.config, options.output
  368. def main():
  369. """
  370. The main Method
  371. """
  372. (config_file, output_dir) = parse_cmdline( sys.argv )
  373. # right to let us load the file now
  374. try:
  375. documentation = bb.parse.handle( config_file, bb.data.init() )
  376. except IOError:
  377. bb.fatal( "Unable to open %s" % config_file )
  378. except bb.parse.ParseError:
  379. bb.fatal( "Unable to parse %s" % config_file )
  380. if isinstance(documentation, dict):
  381. documentation = documentation[""]
  382. # Assuming we've the file loaded now, we will initialize the 'tree'
  383. doc = Documentation()
  384. # defined states
  385. state_begin = 0
  386. state_see = 1
  387. state_group = 2
  388. for key in bb.data.keys(documentation):
  389. data = documentation.getVarFlag(key, "doc", False)
  390. if not data:
  391. continue
  392. # The Documentation now starts
  393. doc_ins = DocumentationItem()
  394. doc_ins.setName(key)
  395. tokens = data.split(' ')
  396. state = state_begin
  397. string= ""
  398. for token in tokens:
  399. token = token.strip(',')
  400. if not state == state_see and token == "@see":
  401. state = state_see
  402. continue
  403. elif not state == state_group and token == "@group":
  404. state = state_group
  405. continue
  406. if state == state_begin:
  407. string += " %s" % token
  408. elif state == state_see:
  409. doc_ins.addRelation(token)
  410. elif state == state_group:
  411. doc_ins.addGroup(token)
  412. # set the description
  413. doc_ins.setDescription(string)
  414. doc.insert_doc_item(doc_ins)
  415. # let us create the HTML now
  416. bb.utils.mkdirhier(output_dir)
  417. os.chdir(output_dir)
  418. # Let us create the sites now. We do it in the following order
  419. # Start with the index.html. It will point to sites explaining all
  420. # keys and groups
  421. html_slave = HTMLFormatter()
  422. f = file('style.css', 'w')
  423. print >> f, html_slave.createCSS()
  424. f = file('index.html', 'w')
  425. print >> f, html_slave.createIndex()
  426. f = file('all_groups.html', 'w')
  427. print >> f, html_slave.createGroupsSite(doc)
  428. f = file('all_keys.html', 'w')
  429. print >> f, html_slave.createKeysSite(doc)
  430. # now for each group create the site
  431. for group in doc.groups():
  432. f = file('group%s.html' % group, 'w')
  433. print >> f, html_slave.createGroupSite(group, doc.group_content(group))
  434. # now for the keys
  435. for key in doc.doc_keys():
  436. f = file('key%s.html' % doc.doc_item(key).name(), 'w')
  437. print >> f, html_slave.createKeySite(doc.doc_item(key))
  438. if __name__ == "__main__":
  439. main()