markdownout.py
3.26 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
#! /usr/bin/env python3
"""
Class to generate Markdown documentation pages from parsed module doc strings
"""
from xml.sax.saxutils import escape
import codecs
import os
class MarkdownOutput():
def __init__(self, module_groups):
self._outputs = {}
result = """
# Modules & Commands Reference
The following pages document the PX4 modules, drivers and commands. They
describe the provided functionality, high-level implementation overview and how
to use the command-line interface.
> **Note** **This is auto-generated from the source code** and contains the
> most recent modules documentation.
It is not a complete list and NuttX provides some additional commands
as well (such as `free`). Use `help` on the console to get a list of all
available commands, and in most cases `command help` will print the usage.
Since this is generated from source, errors must be reported/fixed
in the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) repository.
The documentation pages can be generated by running the following command from
the root of the Firmware directory:
```
make module_documentation
```
The generated files will be written to the `modules` directory.
## Categories
"""
for category in sorted(module_groups):
result += "- [%s](modules_%s.md)\n" % (category.capitalize(), category)
self._outputs['main'] = result
for category in sorted(module_groups):
result = "# Modules Reference: %s\n" % category.capitalize()
subcategories = module_groups[category]
if len(subcategories) > 1:
result += 'Subcategories:\n'
for subcategory in subcategories:
if subcategory == '':
continue
subcategory_label = subcategory.replace('_', ' ').title()
subcategory_file_name = category+'_'+subcategory
result += '- [%s](modules_%s.md)\n' % (subcategory_label, subcategory_file_name)
# add a sub-page for the subcategory
result_subpage = '# Modules Reference: %s (%s)\n' % \
(subcategory_label, category.capitalize())
result_subpage += self._ProcessModules(subcategories[subcategory])
self._outputs[subcategory_file_name] = result_subpage
result += '\n' + self._ProcessModules(subcategories[''])
self._outputs[category] = result
def _ProcessModules(self, module_list):
result = ''
for module in module_list:
result += "## %s\n" % module.name()
result += "Source: [%s](https://github.com/PX4/Firmware/tree/master/src/%s)\n\n" % (module.scope(), module.scope())
doc = module.documentation()
if len(doc) > 0:
result += "%s\n" % doc
usage_string = module.usage_string()
if len(usage_string) > 0:
result += '<a id="%s_usage"></a>\n### Usage\n```\n%s\n```\n' % (module.name(), usage_string)
return result
def Save(self, dirname):
for output_name in self._outputs:
output = self._outputs[output_name]
with codecs.open(os.path.join(dirname, 'modules_'+output_name+'.md'), 'w', 'utf-8') as f:
f.write(output)