borgbackup/borg
1
1
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2024-09-19 08:18:10 +03:00
Code Issues Projects Releases Wiki Activity

man pages: add EXAMPLES

Browse Source 
hacky, but works. Better would be to make a separate docs/examples dir
with only the examples in them, separated by command.

Or, putting these different sections; DESCRIPTION, EXAMPLES and NOTES
into the --help doc, but separately of course, so that they can be aptly
formatted for different media (html, --help, man).
This commit is contained in:
Marian Beermann 2017-02-05 14:08:53 +01:00
parent e5ea876f90
commit 83bb25d848
1 changed files with 35 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
setup.py
View File

@ -347,6 +347,12 @@ class build_man(Command):
'extract': ('mount', ),
}
rst_prelude = textwrap.dedent("""
.. role:: ref(title)
.. |project_name| replace:: Borg
""")
def initialize_options(self):
pass
@ -379,14 +385,12 @@ def generate_level(self, prefix, parser, Archiver):
continue
man_title = 'borg-' + command.replace(' ', '-')
print('building man page %-40s' % (man_title + '(1)'), end='\r', file=sys.stderr)
print('building man page', man_title + '(1)', file=sys.stderr)
if self.generate_level(command + ' ', parser, Archiver):
continue
doc = io.StringIO()
write = self.printer(doc)
doc, write = self.new_doc()
self.write_man_header(write, man_title, parser.description)
self.write_heading(write, 'SYNOPSIS')
@ -402,14 +406,15 @@ def generate_level(self, prefix, parser, Archiver):
write()
self.write_options(write, parser)
self.write_examples(write, command)
self.write_see_also(write, man_title)
self.gen_man_page(man_title, doc.getvalue())
# Generate the borg-common(1) man page with the common options.
if 'create' in choices:
doc = io.StringIO()
write = self.printer(doc)
doc, write = self.new_doc()
man_title = 'borg-common'
self.write_man_header(write, man_title, 'Common options of Borg commands')
@ -424,16 +429,21 @@ def generate_level(self, prefix, parser, Archiver):
def build_topic_pages(self, Archiver):
for topic, text in Archiver.helptext.items():
doc = io.StringIO()
write = self.printer(doc)
doc, write = self.new_doc()
man_title = 'borg-' + topic
print('building man page %-40s' % (man_title + '(1)'), end='\r', file=sys.stderr)
print('building man page', man_title + '(1)', file=sys.stderr)
self.write_man_header(write, man_title, 'Details regarding ' + topic)
self.write_heading(write, 'DESCRIPTION')
write(text)
self.gen_man_page(man_title, doc.getvalue())
def new_doc(self):
doc = io.StringIO(self.rst_prelude)
doc.read()
write = self.printer(doc)
return doc, write
def printer(self, fd):
def write(*args, **kwargs):
print(*args, file=fd, **kwargs)
@ -457,6 +467,22 @@ def write_man_header(self, write, title, description):
write(':Manual group: borg backup tool')
write()
def write_examples(self, write, command):
with open('docs/usage.rst') as fd:
usage = fd.read()
usage_include = '.. include:: usage/%s.rst.inc' % command
begin = usage.find(usage_include)
end = usage.find('.. include', begin + 1)
examples = usage[begin:end]
examples = examples.replace(usage_include, '')
examples = examples.replace('Examples\n~~~~~~~~', '')
examples = examples.replace('Miscellaneous Help\n------------------', '')
examples = re.sub('^(~+)$', lambda matches: '+' * len(matches.group(0)), examples, flags=re.MULTILINE)
examples = examples.strip()
if examples:
self.write_heading(write, 'EXAMPLES', '-')
write(examples)
def write_see_also(self, write, man_title):
see_also = self.see_also.get(man_title.replace('borg-', ''), ())
see_also = ['`borg-%s(1)`' % s for s in see_also]