Merge pull request #275 from rebortg/cfgcmd_crux

Sphinx: backport cfgcmd and opcmd directives to crux

10 files changed, 370 insertions, 16 deletions

diff --git a/docs/_ext/vyos.py b/docs/_ext/vyos.py
new file mode 100644
index 00000000..ae02f91f
--- /dev/null
+++ b/docs/_ext/vyos.py
@@ -0,0 +1,290 @@
+from docutils import nodes, utils
+from docutils.parsers.rst.roles import set_classes
+from docutils.parsers.rst import Directive
+from sphinx.util.docutils import SphinxDirective
+
+
+def setup(app):
+
+    app.add_config_value(
+        'vyos_phabricator_url',
+        'https://phabricator.vyos.net/', ''
+    )
+    app.add_role('vytask', vytask_role)
+    app.add_role('cfgcmd', cmd_role)
+    app.add_role('opcmd', cmd_role)
+
+    print(app.config.vyos_phabricator_url)
+
+    app.add_node(
+        inlinecmd,
+        html=(inlinecmd.visit_span, inlinecmd.depart_span),
+        latex=(inlinecmd.visit_tex, inlinecmd.depart_tex),
+        text=(inlinecmd.visit_span, inlinecmd.depart_span)
+    )
+
+    app.add_node(
+        CmdDiv,
+        html=(CmdDiv.visit_div, CmdDiv.depart_div),
+        latex=(CmdDiv.visit_tex, CmdDiv.depart_tex),
+        text=(CmdDiv.visit_div, CmdDiv.depart_div)
+    )
+    app.add_node(
+        CmdBody,
+        html=(CmdBody.visit_div, CmdBody.depart_div),
+        latex=(CmdBody.visit_tex, CmdBody.depart_tex),
+        text=(CmdBody.visit_div, CmdBody.depart_div)
+    )
+    app.add_node(
+        CmdHeader,
+        html=(CmdHeader.visit_div, CmdHeader.depart_div),
+        latex=(CmdHeader.tex, CmdHeader.tex),
+        text=(CmdHeader.visit_div, CmdHeader.depart_div)
+    )
+    app.add_node(CfgcmdList)
+    app.add_directive('cfgcmdlist', CfgcmdlistDirective)
+
+    app.add_node(OpcmdList)
+    app.add_directive('opcmdlist', OpcmdlistDirective)
+
+    app.add_directive('cfgcmd', CfgCmdDirective)
+    app.add_directive('opcmd', OpCmdDirective)
+    app.connect('doctree-resolved', process_cmd_nodes)
+
+
+class CfgcmdList(nodes.General, nodes.Element):
+    pass
+
+
+class OpcmdList(nodes.General, nodes.Element):
+    pass
+
+import json
+
+class CmdHeader(nodes.General, nodes.Element):
+
+    @staticmethod
+    def visit_div(self, node):
+        self.body.append(self.starttag(node, 'div'))
+
+    @staticmethod
+    def depart_div(self, node=None):
+        # self.body.append('</div>\n')
+        self.body.append('<a class="cmdlink" href="#%s" ' %
+                        node.children[0]['refid'] +
+                        'title="%s"></a></div>' % (
+                        'Permalink to this Command'))
+
+    @staticmethod
+    def tex(self, node=None):
+        pass
+
+
+class CmdDiv(nodes.General, nodes.Element):
+
+    @staticmethod
+    def visit_div(self, node):
+        self.body.append(self.starttag(node, 'div'))
+
+    @staticmethod
+    def depart_div(self, node=None):
+        self.body.append('</div>\n')
+
+    @staticmethod
+    def tex(self, node=None):
+        pass
+
+    @staticmethod
+    def visit_tex(self, node=None):
+        self.body.append('\n\n\\begin{changemargin}{0cm}{0cm}\n')
+
+    @staticmethod
+    def depart_tex(self, node=None):
+        self.body.append('\n\\end{changemargin}\n\n')
+
+class CmdBody(nodes.General, nodes.Element):
+
+    @staticmethod
+    def visit_div(self, node):
+        self.body.append(self.starttag(node, 'div'))
+
+    @staticmethod
+    def depart_div(self, node=None):
+        self.body.append('</div>\n')
+
+    @staticmethod
+    def visit_tex(self, node=None):
+        self.body.append('\n\n\\begin{changemargin}{0.5cm}{0.5cm}\n')
+
+
+    @staticmethod
+    def depart_tex(self, node=None):
+        self.body.append('\n\\end{changemargin}\n\n')
+
+
+    @staticmethod
+    def tex(self, node=None):
+        pass
+
+
+class inlinecmd(nodes.inline):
+
+    @staticmethod
+    def visit_span(self, node):
+        self.body.append(self.starttag(node, 'span'))
+
+    @staticmethod
+    def depart_span(self, node=None):
+        self.body.append('</span>\n')
+
+    @staticmethod
+    def visit_tex(self, node=None):
+        self.body.append(r'\sphinxbfcode{\sphinxupquote{')
+        #self.literal_whitespace += 1
+
+    @staticmethod
+    def depart_tex(self, node=None):
+        self.body.append(r'}}')
+        #self.literal_whitespace -= 1
+
+
+class CfgcmdlistDirective(Directive):
+
+    def run(self):
+        return [CfgcmdList('')]
+
+
+class OpcmdlistDirective(Directive):
+
+    def run(self):
+        return [OpcmdList('')]
+
+
+class CmdDirective(SphinxDirective):
+
+    has_content = True
+    custom_class = ''
+
+    def run(self):
+        title_list = []
+        content_list = []
+        title_text = ''
+        content_text = ''
+        has_body = False
+
+        cfgmode = self.custom_class + "cmd"
+
+        if '' in self.content:
+            index = self.content.index('')
+            title_list = self.content[0:index]
+            content_list = self.content[index + 1:]
+            title_text = ' '.join(title_list)
+            content_text = '\n'.join(content_list)
+            has_body = True
+        else:
+            title_text = ' '.join(self.content)
+
+        anchor_id = nodes.make_id(self.custom_class + "cmd-" + title_text)
+        target = nodes.target(ids=[anchor_id])
+
+        panel_name = 'cmd-{}'.format(self.custom_class)
+        panel_element = CmdDiv()
+        panel_element['classes'] += ['cmd', panel_name]
+
+        heading_element = CmdHeader(title_text)
+        title_nodes, messages = self.state.inline_text(title_text,
+                                                       self.lineno)
+
+        title = inlinecmd(title_text, '', *title_nodes)
+        target['classes'] += []
+        title['classes'] += [cfgmode]
+        heading_element.append(target)
+        heading_element.append(title)
+
+        heading_element['classes'] += [self.custom_class + 'cmd-heading']
+
+        panel_element.append(heading_element)
+
+        append_list = {
+            'docname': self.env.docname,
+            'cmdnode': title.deepcopy(),
+            'cmd': title_text,
+            'target': target,
+        }
+
+        if cfgmode == 'opcmd':
+            if not hasattr(self.env, "vyos_opcmd"):
+                self.env.vyos_opcmd = []
+            self.env.vyos_opcmd.append(append_list)
+
+        if cfgmode == 'cfgcmd':
+            if not hasattr(self.env, "vyos_cfgcmd"):
+                self.env.vyos_cfgcmd = []
+            self.env.vyos_cfgcmd.append(append_list)
+
+        if has_body:
+            body_element = CmdBody(content_text)
+            self.state.nested_parse(
+                content_list,
+                self.content_offset,
+                body_element
+            )
+
+            body_element['classes'] += [self.custom_class + 'cmd-body']
+            panel_element.append(body_element)
+        return [panel_element]
+
+
+class OpCmdDirective(CmdDirective):
+    custom_class = 'op'
+
+
+class CfgCmdDirective(CmdDirective):
+    custom_class = 'cfg'
+
+
+def process_cmd_node(app, cmd, fromdocname):
+    para = nodes.paragraph()
+    newnode = nodes.reference('', '')
+    innernode = cmd['cmdnode']
+    newnode['refdocname'] = cmd['docname']
+    newnode['refuri'] = app.builder.get_relative_uri(
+        fromdocname, cmd['docname'])
+    newnode['refuri'] += '#' + cmd['target']['refid']
+    newnode['classes'] += ['cmdlink']
+    newnode.append(innernode)
+    para += newnode
+    return para
+
+
+def process_cmd_nodes(app, doctree, fromdocname):
+    env = app.builder.env
+
+    for node in doctree.traverse(CfgcmdList):
+        content = []
+
+        for cmd in sorted(env.vyos_cfgcmd, key=lambda i: i['cmd']):
+            content.append(process_cmd_node(app, cmd, fromdocname))
+        node.replace_self(content)
+
+    for node in doctree.traverse(OpcmdList):
+        content = []
+
+        for cmd in sorted(env.vyos_opcmd, key=lambda i: i['cmd']):
+            content.append(process_cmd_node(app, cmd, fromdocname))
+        node.replace_self(content)
+
+
+def vytask_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    app = inliner.document.settings.env.app
+    base = app.config.vyos_phabricator_url
+    ref = base + str(text)
+    set_classes(options)
+    node = nodes.reference(
+        rawtext, utils.unescape(str(text)), refuri=ref, **options)
+    return [node], []
+
+
+def cmd_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    node = nodes.literal(text, text)
+    return [node], []
\ No newline at end of file
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
index a8b94c6e..7faf7b7f 100644
--- a/docs/_static/css/custom.css
+++ b/docs/_static/css/custom.css
@@ -1,3 +1,64 @@
+span.opcmd,
+span.cfgcmd {
+    font-weight: bold;
+    background-color: transparent;
+    border: none;
+    padding: 0;
+    font-size: 100% !important;
+    max-width: 100%;
+    color: #000;
+    font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
+}
+
+.opcmd-heading,
+.cfgcmd-heading {
+    display: inline-block;
+    margin: 6px 0;
+    font-size: 90%;
+    line-height: normal;
+    background: #e7f2fa;
+    color: #2980B9;
+    border-top: solid 3px #6ab0de;
+    border-top-width: 3px;
+    border-top-style: solid;
+    border-top-color: rgb(106, 176, 222);
+    padding: 6px;
+}
+
+.opcmd-body,
+.cfgcmd-body {
+    margin: 6px 0;
+    padding-left: 12px;
+}
+
+
+
+.cfgcmd-heading .cmdlink:after,
+.opcmd-heading .cmdlink:after {
+    content: "";
+    font-family: FontAwesome
+}
+
+
+.cfgcmd-heading:not(:hover) .cmdlink,
+.opcmd-heading:not(:hover) .cmdlink {
+    display: none;
+}
+
+
+a.cmdlink {
+    font-size: 80%;
+    margin-left: 6px;
+}
+
+a.cmdlink span{
+    color: #2980B9;
+}
+
+a.cmdlink span:hover{
+    color: #3091d1;
+}
+
 .wy-nav-content {
   max-width : none;
 }
diff --git a/docs/conf.py b/docs/conf.py
index d8f35063..e2a059f2 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -12,9 +12,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.append(os.path.abspath("./_ext"))
 
 
 # -- Project information -----------------------------------------------------
@@ -40,7 +40,9 @@ release = u'1.2.x (crux)'
 # ones.
 extensions = ['sphinx.ext.intersphinx',
               'sphinx.ext.todo',
-              'sphinx.ext.ifconfig']
+              'sphinx.ext.ifconfig',
+              'vyos'
+            ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -169,5 +171,4 @@ texinfo_documents = [
 ]
 
 def setup(app):
-    app.add_object_type('opcmd', 'opcmd')
-    app.add_object_type('cfcmd', 'cfcmd')
+    pass
diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst
index 8d191a9f..2ceaeda8 100644
--- a/docs/contributing/build-vyos.rst
+++ b/docs/contributing/build-vyos.rst
@@ -38,7 +38,7 @@ To be able to use Docker_, the current non-root user should be added to the
 
 
 Generating the container
-----------------------
+------------------------
 
 The container can built by hand or by fetching the pre-built one from
 DockerHub. Using the pre-built VyOS DockerHub organisation (https://hub.docker.com/u/vyos) will
diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst
index 547c238b..f2fdb313 100644
--- a/docs/contributing/development.rst
+++ b/docs/contributing/development.rst
@@ -31,6 +31,7 @@ eases the automatic generation of a changelog file.
 A good approach for writing commit messages is actually to have a look at the
 file(s) history by invoking ``git log path/to/file.txt``.
 
+.. _prepare_commit:
 
 Preparding patch/commit
 ^^^^^^^^^^^^^^^^^^^^^^^
@@ -81,12 +82,12 @@ post: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
 
   * All text of the commit message should be wrapped at 72 characters if
     possible which makes reading commit logs easier with ``git log`` on a
-	standard terminal (which happens to be 80x25)
+    standard terminal (which happens to be 80x25)
 
   * If applicable a reference to a previous commit should be made linking
     those commits nicely when browsing the history: ``After commit abcd12ef
-	("snmp: this is a headline") a Python import statement is missing,
-	throwing the follwoing exception: ABCDEF``
+    ("snmp: this is a headline") a Python import statement is missing,
+    throwing the following exception: ABCDEF``
 
 * Always use the ``-x`` option to the ``git cherry-pick`` command when back or
   forward porting an individual commit. This automatically appends the line:
diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst
index 601688ee..40edf750 100644
--- a/docs/contributing/documentation.rst
+++ b/docs/contributing/documentation.rst
@@ -30,7 +30,7 @@ project maintainer can push to the official repository. This allows the
 maintainer to accept commits from any developer without giving them write
 access to the official codebase.
 
-.. node:: Updates to our documentation should be delivered by a GitHub
+.. note:: Updates to our documentation should be delivered by a GitHub
    pull-request. This requires you already have a GitHub account.
 
 * Fork this project on GitHub https://github.com/vyos/vyos-documentation/fork
diff --git a/docs/contributing/vyos_cli.rst b/docs/contributing/vyos_cli.rst
index 322b0be6..0dd288b0 100644
--- a/docs/contributing/vyos_cli.rst
+++ b/docs/contributing/vyos_cli.rst
@@ -183,7 +183,7 @@ Examples:
 * Bad: "Set TCP connection timeout"
 
 If a verb is essential, keep it. For example, in the help text of ``set system
-ipv6 disable-forwarding`, "Disable IPv6 forwarding on all interfaces" is a
+ipv6 disable-forwarding``, "Disable IPv6 forwarding on all interfaces" is a
 perfectly justified wording.
 
 Prefer infinitives
diff --git a/docs/qos.rst b/docs/qos.rst
index 51ed0893..49122434 100644
--- a/docs/qos.rst
+++ b/docs/qos.rst
@@ -423,7 +423,7 @@ fashion. You can configure the length of the queue.
 
 
 
-.. _FQ-CoDel
+.. _FQ-CoDel:
 
 FQ-CoDel
 --------
diff --git a/docs/routing/multicast.rst b/docs/routing/multicast.rst
index a6310fa3..421c9f0f 100644
--- a/docs/routing/multicast.rst
+++ b/docs/routing/multicast.rst
@@ -31,7 +31,7 @@ source-specific multicast).
 
 
 Example
--------
+=======
 
 In the following example we can see a basic multicast setup:
 
@@ -87,7 +87,7 @@ In the following example we can see a basic multicast setup:
 
 
 Basic commands
---------------
+==============
 
 These are the commands for a basic setup.
 
@@ -114,7 +114,7 @@ These are the commands for a basic setup.
 
 
 Tuning commands
----------------
+===============
 
 You can also tune multicast with the following commands.
 
diff --git a/requirements.txt b/requirements.txt
index 0def141f..a5a4e3a3 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,3 +1,4 @@
 Sphinx>=1.4.3
 sphinx-rtd-theme
 setuptools
+docutils