From mboxrd@z Thu Jan 1 00:00:00 1970 Return-path: Received: from s3.sipsolutions.net ([5.9.151.49]:43448 "EHLO sipsolutions.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754833AbcJUVT5 (ORCPT ); Fri, 21 Oct 2016 17:19:57 -0400 Message-ID: <1477084793.4068.63.camel@sipsolutions.net> (sfid-20161021_232001_766618_35970376) Subject: Re: sequence diagrams in rst documentation From: Johannes Berg To: Markus Heiser Cc: Jani Nikula , Jonathan Corbet , linux-wireless@vger.kernel.org, linux-doc Date: Fri, 21 Oct 2016 23:19:53 +0200 In-Reply-To: References: <1476190613-2403-1-git-send-email-johannes@sipsolutions.net> <20161011072119.7ad4e3a3@lwn.net> <1476193466.4118.10.camel@sipsolutions.net> <1476194038.4118.11.camel@sipsolutions.net> <1476791021.6425.25.camel@sipsolutions.net> <20161018175236.75c8c4e2@lwn.net> <1476863488.5927.10.camel@sipsolutions.net> <1477053099.4068.42.camel@sipsolutions.net> <87k2d1q2qx.fsf@intel.com> <1477055055.4068.46.camel@sipsolutions.net> Content-Type: text/plain; charset="UTF-8" Mime-Version: 1.0 Sender: linux-wireless-owner@vger.kernel.org List-ID: On Fri, 2016-10-21 at 18:11 +0200, Markus Heiser wrote: > Yes and No. It depends on the tools (toolchains) we want to use. > As far as I can see from a abstract POV it should by simple for > math:: / since we already use/need LaTeX for PDF, for other tools > I have to look. Not sure if we were talking past each other - but the pass-through is actually really simple - example patch below. This makes it output an SVG (with fallback to PNG even) into the HTML, a PDF into the PDF, and plain pre-formatted text for both when the plantuml sphinx plugin isn't installed. johannes diff --git a/Documentation/conf.py b/Documentation/conf.py index bf6f310e5170..2c00ab6f0baf 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -34,7 +34,8 @@ from load_config import loadConfig # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include', 'cdomain'] +extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include', 'cdomain', + 'plantuml'] # The name of the math extension changed on Sphinx 1.4 if minor > 3: @@ -494,6 +495,9 @@ pdf_documents = [ kerneldoc_bin = '../scripts/kernel-doc' kerneldoc_srctree = '..' +plantuml_output_format = "svg" +plantuml_latex_output_format = "pdf" + # ------------------------------------------------------------------------------ # Since loadConfig overwrites settings from the global namespace, it has to be # the last statement in the conf.py file diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 8e259c5d0322..e0d4f24b6039 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -7,6 +7,12 @@ of device drivers. This document is an only somewhat organized collection of some of those interfaces — it will hopefully get better over time! The available subsections can be seen below. +.. uml:: + + Alice -> Bob: Hi! + Alice <- Bob: How are you? + + .. class:: toc-title Table of contents diff --git a/Documentation/sphinx/dummy.py b/Documentation/sphinx/dummy.py new file mode 100644 index 000000000000..cfac42886ebd --- /dev/null +++ b/Documentation/sphinx/dummy.py @@ -0,0 +1,24 @@ +from sphinx.util.compat import Directive +from docutils import nodes +from docutils.parsers.rst import directives + +class IgnoreOptions(object): + def __getitem__(self, key): + return directives.unchanged + +def create_setup(directives): + def setup(app): + for d in directives: + class TextDirective(Directive): + has_content = True + option_spec = IgnoreOptions() + + def run(self): + text = '\n'.join(self.content) + return [nodes.literal_block('', text, + classes=['code', + 'missing-plugin', + 'missing-plugin-%s' % d])] + + app.add_directive(d, TextDirective) + return setup diff --git a/Documentation/sphinx/plantuml.py b/Documentation/sphinx/plantuml.py new file mode 100644 index 000000000000..0007bc7f24fd --- /dev/null +++ b/Documentation/sphinx/plantuml.py @@ -0,0 +1,7 @@ +# -*- coding: utf-8 -*- +from dummy import create_setup + +try: + from sphinxcontrib.plantuml import * +except: + setup = create_setup(['uml'])