Messages in this thread | | | Subject | Re: make xmldocs failed with error after 4.17 merge period | From | Markus Heiser <> | Date | Fri, 6 Apr 2018 12:03:55 +0200 |
| |
> Am 06.04.2018 um 11:11 schrieb Heikki Krogerus <heikki.krogerus@linux.intel.com>: [...]
>>>>>> An ascii graphic in typec.rst cause the error. >>>>> >>>>> Thanks for the report. I'm going to propose that we fix this by >>>>> marking the ascii art as comment: >>>>> >>>>> diff --git a/Documentation/driver-api/usb/typec.rst b/Documentation/driver-api/usb/typec.rst >>>>> index feb31946490b..972c11bf4141 100644 >>>>> --- a/Documentation/driver-api/usb/typec.rst >>>>> +++ b/Documentation/driver-api/usb/typec.rst >>>>> @@ -212,7 +212,7 @@ port drivers can use USB Role Class API with those. >>>>> >>>>> Illustration of the muxes behind a connector that supports an alternate mode: >>>>> >>>>> - ------------------------ >>>>> +.. ------------------------ >>>>> | Connector | >>>>> ------------------------ >>>>> | | >>>>> >>>>> I hope that works. >>>> >>>> Try it and see! :) >>> >>> It will fix this issue. I was just wondering if use of ascii art is >>> acceptable in general with the .rst files? But then again, why >>> wouldn't it be.
[...]
> I was propsed to use something called "Literal Block" with ascii art. > http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#literal-blocks
about *ASCII-art*: see fix from Jani ...
https://www.mail-archive.com/linux-doc@vger.kernel.org/msg19302.html
where the '::' is a short-markup for a literal-block.
>> There are ways to do this, look at how the v4l2 and I think the drm >> subsystems handle ascii art such that "real" drawings end up being >> produced. > > Thanks. I did not actually find anything else except use of tables and > code-blocks in v4l documentation. Is that what you were referring?
If it is about *figures*: we have a directive named 'kernel-figure', which is a full replacement of the 'figure' directive from Sphinx-Doc. In addition it supports *inline* SVG and DOT markups. Read:
https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#figures-images
-- Markus --
| |