diff options
| -rw-r--r-- | docs/_ext/vyos.py | 290 | ||||
| -rw-r--r-- | docs/_static/css/custom.css | 61 | ||||
| -rw-r--r-- | docs/conf.py | 13 | ||||
| -rw-r--r-- | docs/contributing/build-vyos.rst | 2 | ||||
| -rw-r--r-- | docs/contributing/development.rst | 7 | ||||
| -rw-r--r-- | docs/contributing/documentation.rst | 2 | ||||
| -rw-r--r-- | docs/contributing/vyos_cli.rst | 2 | ||||
| -rw-r--r-- | docs/qos.rst | 2 | ||||
| -rw-r--r-- | docs/routing/multicast.rst | 6 | ||||
| -rw-r--r-- | requirements.txt | 1 |
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 |