diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_ext/vyos.py | 290 | ||||
| -rw-r--r-- | docs/_static/css/custom.css | 54 | ||||
| -rw-r--r-- | docs/appendix/cmd-index.rst | 12 | ||||
| -rw-r--r-- | docs/conf.py | 21 | ||||
| -rw-r--r-- | docs/contributing/documentation.rst | 14 | ||||
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/routing/bgp.rst | 2 |
7 files changed, 381 insertions, 13 deletions
diff --git a/docs/_ext/vyos.py b/docs/_ext/vyos.py new file mode 100644 index 00000000..7a3d75ba --- /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], [] diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css index a8b94c6e..a1e34259 100644 --- a/docs/_static/css/custom.css +++ b/docs/_static/css/custom.css @@ -1,3 +1,57 @@ +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; +} + .wy-nav-content { max-width : none; } diff --git a/docs/appendix/cmd-index.rst b/docs/appendix/cmd-index.rst new file mode 100644 index 00000000..28366d02 --- /dev/null +++ b/docs/appendix/cmd-index.rst @@ -0,0 +1,12 @@ +.. cmd-index: + +Operational Command Refercence +============================== + +.. opcmdlist:: + + +Configuration Command Refercence +================================ + +.. cfgcmdlist::
\ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 539f828d..d82f292c 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")) from docutils import nodes, utils from docutils.parsers.rst.roles import set_classes @@ -43,7 +43,9 @@ release = u'1.3.x (equuleus)' extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.ifconfig', - 'sphinx.ext.graphviz'] + 'sphinx.ext.graphviz', + 'vyos' +] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -136,6 +138,9 @@ latex_elements = { # Latex figure (float) alignment # # 'figure_align': 'htbp', + 'preamble': r'''\def\changemargin#1#2{\list{}{\rightmargin#2\leftmargin#1}\item[]} +\let\endchangemargin=\endlist''', + } # Grouping the document tree into LaTeX files. List of tuples @@ -183,10 +188,4 @@ def vytask_role(name, rawtext, text, lineno, inliner, options={}, content=[]): def setup(app): - app.add_config_value( - 'vyos_phabricator_url', - 'https://phabricator.vyos.net/', '' - ) - app.add_role('vytask', vytask_role) - app.add_object_type('opcmd', 'opcmd') - app.add_object_type('cfgcmd', 'cfgcmd') + pass diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst index 2d9f14d1..8102e9a9 100644 --- a/docs/contributing/documentation.rst +++ b/docs/contributing/documentation.rst @@ -171,6 +171,12 @@ descriptive way in the resulting HTML/PDF manual. This will configure a static ARP entry always resolving `192.0.2.100` to `00:53:27:de:23:aa`. +For a inline configuration level command use ``:cfgcmd:`` + +.. code-block:: none + + :cfgcmd:`set interface ethernet eth0` + opcmd """"" @@ -186,10 +192,16 @@ descriptive way in the resulting HTML/PDF manual. Display all known ARP table entries spanning across all interfaces +For a inline operational level command use ``:opcmd:`` + +.. code-block:: none + + :opcmd:`add system image` + vytask """""" -When referencing to VyOS Phabricator Tasks, there is a custom Spinx Markup +When referencing to VyOS Phabricator Tasks, there is a custom Sphinx Markup command called ``vytask`` which automatically renders to a proper Phabricator URL. This is heavily used in the :ref:`release-notes` section. diff --git a/docs/index.rst b/docs/index.rst index 0b9138a4..f6b3d595 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -54,6 +54,7 @@ VyOS User Guide appendix/release-notes appendix/examples/index + appendix/cmd-index appendix/commandtree/index appendix/vyos-on-vmware appendix/vyos-on-baremetal diff --git a/docs/routing/bgp.rst b/docs/routing/bgp.rst index 14ea1238..41be5c6c 100644 --- a/docs/routing/bgp.rst +++ b/docs/routing/bgp.rst @@ -76,7 +76,7 @@ bottom until one of the factors can be used. 6. **MED check** Where routes with a MED were received from the same AS, prefer the route - with the lowest MED. :ref:`bgp-med`. + with the lowest MED. 7. **External check** |