From 7284413e3f25f9616fdba0b7e83db26068b4f76a Mon Sep 17 00:00:00 2001 From: Marian Beermann Date: Mon, 22 May 2017 17:30:45 +0200 Subject: [PATCH] docs: borg_domain for custom priority index entries --- docs/borg_domain.py | 102 ++++++++++++++++++++++ docs/conf.py | 14 ++- docs/usage/benchmark_crud.rst.inc | 2 + docs/usage/break-lock.rst.inc | 2 + docs/usage/change-passphrase.rst.inc | 2 + docs/usage/check.rst.inc | 2 + docs/usage/create.rst.inc | 2 + docs/usage/delete.rst.inc | 2 + docs/usage/diff.rst.inc | 2 + docs/usage/export-tar.rst.inc | 2 + docs/usage/extract.rst.inc | 2 + docs/usage/info.rst.inc | 2 + docs/usage/init.rst.inc | 2 + docs/usage/key_change-passphrase.rst.inc | 2 + docs/usage/key_export.rst.inc | 2 + docs/usage/key_import.rst.inc | 2 + docs/usage/key_migrate-to-repokey.rst.inc | 2 + docs/usage/list.rst.inc | 2 + docs/usage/mount.rst.inc | 2 + docs/usage/prune.rst.inc | 2 + docs/usage/recreate.rst.inc | 2 + docs/usage/rename.rst.inc | 2 + docs/usage/serve.rst.inc | 2 + docs/usage/umount.rst.inc | 2 + docs/usage/upgrade.rst.inc | 2 + docs/usage/with-lock.rst.inc | 2 + setup.py | 1 + 27 files changed, 161 insertions(+), 4 deletions(-) create mode 100644 docs/borg_domain.py diff --git a/docs/borg_domain.py b/docs/borg_domain.py new file mode 100644 index 000000000..625e8140b --- /dev/null +++ b/docs/borg_domain.py @@ -0,0 +1,102 @@ +from sphinx import addnodes +from sphinx.domains import Domain, ObjType +from sphinx.locale import l_, _ +from sphinx.directives import ObjectDescription +from sphinx.domains.std import ws_re + + +class BorgObject(ObjectDescription): + indextemplate = l_('%s') + parse_node = None # type: Callable[[GenericObject, BuildEnvironment, unicode, addnodes.desc_signature], unicode] # NOQA + + def handle_signature(self, sig, signode): + # type: (unicode, addnodes.desc_signature) -> unicode + pass + + def add_target_and_index(self, name, sig, signode): + # type: (str, str, addnodes.desc_signature) -> None + # ^ ignore this one, don't insert any markup. + # v- the human text v- the target name + # "borg key change-passphrase" -> "borg-key-change-passphrase" + del name # ignored + targetname = sig.replace(' ', '-') + if self.indextemplate: + colon = self.indextemplate.find(':') + if colon != -1: + indextype = self.indextemplate[:colon].strip() + indexentry = self.indextemplate[colon + 1:].strip() % (sig,) + else: + indextype = 'single' + indexentry = self.indextemplate % (sig,) + self.indexnode['entries'].append((indextype, indexentry, targetname, '', None)) + self.env.domaindata['borg']['objects'][targetname] = self.env.docname, self.objtype, sig + + def run(self): + super().run() + return [self.indexnode] + + +class BorgCommand(BorgObject): + """ + Inserts an index entry and an anchor for a borg command. + + For example, the following snippet creates an index entry about the "borg foo-and-bar" + command as well as a "borg-foo-and-bar" anchor (id). + + .. borg:command:: borg foo-and-bar + """ + + indextemplate = l_('%s (command)') + + +class BorgEnvVar(BorgObject): + """ + Inserts an index entry and an anchor for an environment variable. + (Currently not used) + """ + + indextemplate = l_('%s (environment variable)') + + +class BorgDomain(Domain): + """Land of the Borg.""" + name = 'borg' + label = 'Borg' + object_types = { + 'command': ObjType(l_('command')), + 'env_var': ObjType(l_('env_var')), + } + directives = { + 'command': BorgCommand, + 'env_var': BorgEnvVar, + } + roles = {} + initial_data = { + 'objects': {}, # fullname -> docname, objtype + } + + def clear_doc(self, docname): + # required for incremental builds + try: + del self.data['objects'][docname] + except KeyError: + pass + + def merge_domaindata(self, docnames, otherdata): + # needed due to parallel_read_safe + for fullname, (docname, objtype, sig) in otherdata['objects'].items(): + if docname in docnames: + self.data['objects'][fullname] = (docname, objtype, sig) + + def get_objects(self): + for refname, (docname, objtype, sig) in list(self.data['objects'].items()): + yield sig, sig, objtype, docname, refname, 1 + + +def setup(app): + app.add_domain(BorgDomain) + return { + 'version': 1, + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } diff --git a/docs/conf.py b/docs/conf.py index dc40f2a0c..9a541ac15 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,6 +16,7 @@ # documentation root, use os.path.abspath to make it absolute, like shown here. import sys, os sys.path.insert(0, os.path.abspath('../src')) +sys.path.insert(0, os.path.abspath('.')) from borg import __version__ as sw_version @@ -26,9 +27,7 @@ on_rtd = os.environ.get('READTHEDOCS', None) == 'True' # If your documentation needs a minimal Sphinx version, state it here. #needs_sphinx = '1.0' -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [] +# Extensions are defined at the end of this file. # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -241,7 +240,14 @@ man_pages = [ 1), ] -extensions = ['sphinx.ext.extlinks', 'sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode'] +extensions = [ + 'sphinx.ext.extlinks', + 'sphinx.ext.autodoc', + 'sphinx.ext.todo', + 'sphinx.ext.coverage', + 'sphinx.ext.viewcode', + 'borg_domain', +] extlinks = { 'issue': ('https://github.com/borgbackup/borg/issues/%s', '#'), diff --git a/docs/usage/benchmark_crud.rst.inc b/docs/usage/benchmark_crud.rst.inc index d47e8d62b..604c8795b 100644 --- a/docs/usage/benchmark_crud.rst.inc +++ b/docs/usage/benchmark_crud.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg benchmark crud + .. _borg_benchmark_crud: borg benchmark crud diff --git a/docs/usage/break-lock.rst.inc b/docs/usage/break-lock.rst.inc index 1b8e5915a..24a973039 100644 --- a/docs/usage/break-lock.rst.inc +++ b/docs/usage/break-lock.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg break-lock + .. _borg_break-lock: borg break-lock diff --git a/docs/usage/change-passphrase.rst.inc b/docs/usage/change-passphrase.rst.inc index b0a6c2bbb..7763745cd 100644 --- a/docs/usage/change-passphrase.rst.inc +++ b/docs/usage/change-passphrase.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg change-passphrase + .. _borg_change-passphrase: borg change-passphrase diff --git a/docs/usage/check.rst.inc b/docs/usage/check.rst.inc index 56bc42c8c..73b3ab8e0 100644 --- a/docs/usage/check.rst.inc +++ b/docs/usage/check.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg check + .. _borg_check: borg check diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc index 6b7006cb3..d02072f96 100644 --- a/docs/usage/create.rst.inc +++ b/docs/usage/create.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg create + .. _borg_create: borg create diff --git a/docs/usage/delete.rst.inc b/docs/usage/delete.rst.inc index 0977f0221..fe750682f 100644 --- a/docs/usage/delete.rst.inc +++ b/docs/usage/delete.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg delete + .. _borg_delete: borg delete diff --git a/docs/usage/diff.rst.inc b/docs/usage/diff.rst.inc index 0163c5dc1..12f6e9e37 100644 --- a/docs/usage/diff.rst.inc +++ b/docs/usage/diff.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg diff + .. _borg_diff: borg diff diff --git a/docs/usage/export-tar.rst.inc b/docs/usage/export-tar.rst.inc index f2c4e03a0..4b8015708 100644 --- a/docs/usage/export-tar.rst.inc +++ b/docs/usage/export-tar.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg export-tar + .. _borg_export-tar: borg export-tar diff --git a/docs/usage/extract.rst.inc b/docs/usage/extract.rst.inc index f5b2d4947..95b7f3bb4 100644 --- a/docs/usage/extract.rst.inc +++ b/docs/usage/extract.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg extract + .. _borg_extract: borg extract diff --git a/docs/usage/info.rst.inc b/docs/usage/info.rst.inc index 0376329ab..d6de93499 100644 --- a/docs/usage/info.rst.inc +++ b/docs/usage/info.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg info + .. _borg_info: borg info diff --git a/docs/usage/init.rst.inc b/docs/usage/init.rst.inc index a5a6dbfd8..e23e9cb95 100644 --- a/docs/usage/init.rst.inc +++ b/docs/usage/init.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg init + .. _borg_init: borg init diff --git a/docs/usage/key_change-passphrase.rst.inc b/docs/usage/key_change-passphrase.rst.inc index 7666afc2f..ffc022097 100644 --- a/docs/usage/key_change-passphrase.rst.inc +++ b/docs/usage/key_change-passphrase.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg key change-passphrase + .. _borg_key_change-passphrase: borg key change-passphrase diff --git a/docs/usage/key_export.rst.inc b/docs/usage/key_export.rst.inc index e976ae2dc..6f27448c7 100644 --- a/docs/usage/key_export.rst.inc +++ b/docs/usage/key_export.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg key export + .. _borg_key_export: borg key export diff --git a/docs/usage/key_import.rst.inc b/docs/usage/key_import.rst.inc index ceb89e3f7..92c686718 100644 --- a/docs/usage/key_import.rst.inc +++ b/docs/usage/key_import.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg key import + .. _borg_key_import: borg key import diff --git a/docs/usage/key_migrate-to-repokey.rst.inc b/docs/usage/key_migrate-to-repokey.rst.inc index df242566f..5faabf317 100644 --- a/docs/usage/key_migrate-to-repokey.rst.inc +++ b/docs/usage/key_migrate-to-repokey.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg key migrate-to-repokey + .. _borg_key_migrate-to-repokey: borg key migrate-to-repokey diff --git a/docs/usage/list.rst.inc b/docs/usage/list.rst.inc index cd8db74c9..147de2efe 100644 --- a/docs/usage/list.rst.inc +++ b/docs/usage/list.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg list + .. _borg_list: borg list diff --git a/docs/usage/mount.rst.inc b/docs/usage/mount.rst.inc index 026cc680f..d17f19217 100644 --- a/docs/usage/mount.rst.inc +++ b/docs/usage/mount.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg mount + .. _borg_mount: borg mount diff --git a/docs/usage/prune.rst.inc b/docs/usage/prune.rst.inc index 40e0c26cc..ff288feb5 100644 --- a/docs/usage/prune.rst.inc +++ b/docs/usage/prune.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg prune + .. _borg_prune: borg prune diff --git a/docs/usage/recreate.rst.inc b/docs/usage/recreate.rst.inc index fd3ef446d..3b6fc04ca 100644 --- a/docs/usage/recreate.rst.inc +++ b/docs/usage/recreate.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg recreate + .. _borg_recreate: borg recreate diff --git a/docs/usage/rename.rst.inc b/docs/usage/rename.rst.inc index 13baa7e45..c5e98f318 100644 --- a/docs/usage/rename.rst.inc +++ b/docs/usage/rename.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg rename + .. _borg_rename: borg rename diff --git a/docs/usage/serve.rst.inc b/docs/usage/serve.rst.inc index f3f1aa659..945ff1749 100644 --- a/docs/usage/serve.rst.inc +++ b/docs/usage/serve.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg serve + .. _borg_serve: borg serve diff --git a/docs/usage/umount.rst.inc b/docs/usage/umount.rst.inc index ab02038b8..8be61e6b5 100644 --- a/docs/usage/umount.rst.inc +++ b/docs/usage/umount.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg umount + .. _borg_umount: borg umount diff --git a/docs/usage/upgrade.rst.inc b/docs/usage/upgrade.rst.inc index bdf76ccd3..13fd247ec 100644 --- a/docs/usage/upgrade.rst.inc +++ b/docs/usage/upgrade.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg upgrade + .. _borg_upgrade: borg upgrade diff --git a/docs/usage/with-lock.rst.inc b/docs/usage/with-lock.rst.inc index 47b5abcc3..34a2b69d2 100644 --- a/docs/usage/with-lock.rst.inc +++ b/docs/usage/with-lock.rst.inc @@ -1,5 +1,7 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! +.. borg:command:: borg with-lock + .. _borg_with-lock: borg with-lock diff --git a/setup.py b/setup.py index 5e2d309dd..c676d8c62 100644 --- a/setup.py +++ b/setup.py @@ -258,6 +258,7 @@ class build_usage(Command): params = {"command": command, "command_": command.replace(' ', '_'), "underline": '-' * len('borg ' + command)} + doc.write(".. borg:command:: borg {command}\n\n".format(**params)) doc.write(".. _borg_{command_}:\n\n".format(**params)) doc.write("borg {command}\n{underline}\n::\n\n borg [common options] {command}".format(**params)) self.write_usage(parser, doc)