docs: borg_domain for custom priority index entries

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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)