mirror
/
borg
mirror of https://github.com/borgbackup/borg.git
1
0
Fork 0
Code Issues Releases Wiki Activity

docs: borg_domain for custom priority index entries

This commit is contained in:
Marian Beermann 2017-05-22 17:30:45 +02:00
parent 58791583d9
commit 7284413e3f
27 changed files with 161 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
docs/borg_domain.py Normal file
View File

@ -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,
}

14
docs/conf.py
View File

@ -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', '#'),

2
docs/usage/benchmark_crud.rst.inc
View File

@ -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

2
docs/usage/break-lock.rst.inc
View File

@ -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

2
docs/usage/change-passphrase.rst.inc
View File

@ -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

2
docs/usage/check.rst.inc
View File

@ -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

2
docs/usage/create.rst.inc
View File

@ -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

2
docs/usage/delete.rst.inc
View File

@ -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

2
docs/usage/diff.rst.inc
View File

@ -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

2
docs/usage/export-tar.rst.inc
View File

@ -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

2
docs/usage/extract.rst.inc
View File

@ -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

2
docs/usage/info.rst.inc
View File

@ -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

2
docs/usage/init.rst.inc
View File

@ -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

2
docs/usage/key_change-passphrase.rst.inc
View File

@ -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

2
docs/usage/key_export.rst.inc
View File

@ -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

2
docs/usage/key_import.rst.inc
View File

@ -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

2
docs/usage/key_migrate-to-repokey.rst.inc
View File

@ -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

2
docs/usage/list.rst.inc
View File

@ -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

2
docs/usage/mount.rst.inc
View File

@ -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

2
docs/usage/prune.rst.inc
View File

@ -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

2
docs/usage/recreate.rst.inc
View File

@ -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

2
docs/usage/rename.rst.inc
View File

@ -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

2
docs/usage/serve.rst.inc
View File

@ -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

2
docs/usage/umount.rst.inc
View File

@ -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

2
docs/usage/upgrade.rst.inc
View File

@ -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

2
docs/usage/with-lock.rst.inc
View File

@ -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

1
setup.py
View File

@ -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)