[elbe-devel] [PATCH] Fix badly rendered ELBE sphinx docs

[Bastian Germann]

Please note the mailing list change.
Please post elbe patches there.

Am 24.05.23 um 18:03 schrieb Tobias Deiminger:
> Line join logic in 'elbe xsdtoasciidoc' caused two issues when
> converting xsd annotations to asciidoc syntax:
> - Consecutive text lines were joined with empty string, generating
>    words like "theroot", "theproject", ... in final sphinx documentation,
>    as in example [0].
> - Disregarding line breaks from xml text prevented us from reusing
>    asciidoc syntax. E.g., the bulletin list in project-finetuning
>    misrenders to a single line with literal asterisks in between, as in
>    example [1].
> 
> We can fix this by not joining lines but letting newlines pass from xml
> to asciidoc. We can still remove common xml indent and add new asciidoc
> indent by means of textwrap functions.
> 
> [0] https://elbe-rfs.org/docs/sphinx/article-elbe-schema-reference.html?highlight=artifact#type-finetuning.
> [1] https://elbe-rfs.org/docs/sphinx/article-elbe-schema-reference.html?highlight=artifact#id48
> 
> Signed-off-by: Tobias Deiminger <tobias.deiminger at linutronix.de>

Reviewed-by: Bastian Germann <bage at linutronix.de>

> ---
>   elbepack/xsdtoasciidoc.mako | 6 ++----
>   1 file changed, 2 insertions(+), 4 deletions(-)
> 
> diff --git a/elbepack/xsdtoasciidoc.mako b/elbepack/xsdtoasciidoc.mako
> index 46f0fd4e..79a1e20d 100644
> --- a/elbepack/xsdtoasciidoc.mako
> +++ b/elbepack/xsdtoasciidoc.mako
> @@ -4,6 +4,7 @@
>   ## SPDX-License-Identifier: GPL-3.0-or-later
>   <%
>   import string
> +import textwrap
>   ELEM = "{http://www.w3.org/2001/XMLSchema}element"
>   CPLX = "{http://www.w3.org/2001/XMLSchema}complexType"
>   DOC  = "{http://www.w3.org/2001/XMLSchema}annotation/{http://www.w3.org/2001/XMLSchema}documentation"
> @@ -21,10 +22,7 @@ def docindent(node, indent=0):
>     except:
>       return "FIXME - I have no documentation"
>     else:
> -    lines = s.splitlines()
> -    lines = [l.strip() for l in lines]
> -    lines = map(lambda x: indent*" "+x, lines)
> -    return str('').join(lines).strip()
> +    return textwrap.indent(textwrap.dedent(s), indent*" ").strip("\n")
>   
>   def genlink(typ):
>     if typ.startswith("rfs:"):

-- 
Bastian Germann
Linutronix GmbH | Bahnhofstrasse 3 | D-88690 Uhldingen-Mühlhofen
Phone: +49 7556 25 999 32; Fax.: +49 7556 25 999 99

Hinweise zum Datenschutz finden Sie hier (Informations on data privacy
can be found here): https://linutronix.de/legal/data-protection.php

Linutronix GmbH | Firmensitz (Registered Office): Uhldingen-Mühlhofen |
Registergericht (Registration Court): Amtsgericht Freiburg i.Br., HRB700
806 | Geschäftsführer (Managing Directors): Heinz Egger, Thomas Gleixner,
Sharon Heck, Yulia Beck, Tiffany Silva