Re: [docs] [RFC 0/3] add support for diagrams generated from SVG sources

Re: [docs] [RFC 0/3] add support for diagrams generated from SVG sources

[Michael Opdenacker]

On 5/15/21 9:12 AM, Michael Opdenacker wrote:
>
> My goal is to progressively replace PNG diagrams with SVG ones:
>    - To get high quality definition output documents, in all output formats
>    - To Have the ability to update diagrams
> I would indeed do this very progressively, a little bit every week,
> not at the expense of other tasks.


I forgot to mention that, if this is accepted, I'll also propose
guidelines to create such diagrams, such as using a standard color
palette, standard SVG clipart, standard fonts, etc, so that all diagrams
have a consistent aspect across the whole manual.

Cheers,

Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [RFC 0/3] add support for diagrams generated from SVG sources

[Nicolas Dechesne]

[-- Attachment #1: Type: text/plain, Size: 1671 bytes --]

On Mon, May 17, 2021 at 10:45 AM Michael Opdenacker <
michael.opdenacker@bootlin.com> wrote:

> Hi Nicolas,
>
> On 5/17/21 12:11 AM, Nicolas Dechesne wrote:
> >
> >
> >
> > Getting more svg files is definitely the way to go.. thanks for
> > starting this. It seems like there are sphinx extensions to convert
> > images as needed, e.g.
> > https://www.sphinx-doc.org/en/master/usage/extensions/imgconverter.html
> > <https://www.sphinx-doc.org/en/master/usage/extensions/imgconverter.html
> >
> > or
> > https://github.com/sephalon/sphinxcontrib-svg2pdfconverter
> > <https://github.com/sephalon/sphinxcontrib-svg2pdfconverter>
> > which seems to support inkscape:
> >
> https://github.com/sephalon/sphinxcontrib-svg2pdfconverter/blob/master/sphinxcontrib/inkscapeconverter.py
> > <
> https://github.com/sephalon/sphinxcontrib-svg2pdfconverter/blob/master/sphinxcontrib/inkscapeconverter.py
> >
> >
> > Have you looked into that or not?
>
>
> Not yet, but this sounds like a much better option for converting SVG to
> PNG and PDF, rather than having to do this manually in the Makefile.
> I will try to use those.
>

FWIW, I really like the PDF output.. the whole doc in a single PDF is
great. We should make it a goal for this release cycle to produce and
release PDF (I know some prefer epub.. so perhaps we can do both).

We should probably review the PDF output and tweak it a bit, for example, I
don't think we need the "Current and Previous releases" sections.


>
> Thanks for the great suggestion!
> Michael.
>
> --
> Michael Opdenacker, Bootlin
> Embedded Linux and Kernel engineering
> https://bootlin.com
>
>

[-- Attachment #2: Type: text/html, Size: 3127 bytes --]

Re: [docs] [RFC 0/3] add support for diagrams generated from SVG sources

[Michael Opdenacker]

Hi Nicolas,

On 5/17/21 12:11 AM, Nicolas Dechesne wrote:
>
>
>
> Getting more svg files is definitely the way to go.. thanks for
> starting this. It seems like there are sphinx extensions to convert
> images as needed, e.g.
> https://www.sphinx-doc.org/en/master/usage/extensions/imgconverter.html
> <https://www.sphinx-doc.org/en/master/usage/extensions/imgconverter.html>
> or
> https://github.com/sephalon/sphinxcontrib-svg2pdfconverter
> <https://github.com/sephalon/sphinxcontrib-svg2pdfconverter>
> which seems to support inkscape:
> https://github.com/sephalon/sphinxcontrib-svg2pdfconverter/blob/master/sphinxcontrib/inkscapeconverter.py
> <https://github.com/sephalon/sphinxcontrib-svg2pdfconverter/blob/master/sphinxcontrib/inkscapeconverter.py> 
>
> Have you looked into that or not?


Not yet, but this sounds like a much better option for converting SVG to
PNG and PDF, rather than having to do this manually in the Makefile.
I will try to use those.

Thanks for the great suggestion!
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [RFC 0/3] add support for diagrams generated from SVG sources

[Nicolas Dechesne]

[-- Attachment #1: Type: text/plain, Size: 2795 bytes --]

On Sat, May 15, 2021 at 9:12 AM Michael Opdenacker <
michael.opdenacker@bootlin.com> wrote:

> This RFC proposes modifications to the Makefile and the Sphinx
> configuration (conf.py file) to support:
>
> - The generation of PNG diagrams from SVG sources for the generation
>   of the EPUB manual. Directly using SVG in EPUB shows at least
>   font size and alignment issues.
>
>   The conf.py file has been modified to let the EPUB builder know
>   that it should prefer PNG over SVG when both formats are available.


> - The generation of PDF diagrams from SVG sources for the generation
>   of the PDF manual. PDF output cannot use SVG, and needs PDF diagrams
>   instead.
>
> New diagrams are stored in separate "svg" directories so that generated
> .png and .pdf files can be "gitignored" without ignoring the original
> .png files that have no .svg source.
>
> In the source .rst files, new diagrams can now be included as, for example:
> image:: svg/git-workflow.*
>
> Note that the way the Makefile was modified can most probably be improved,
> as my "make" skills are pretty limited. I'm interested in your suggestions!
>

Getting more svg files is definitely the way to go.. thanks for starting
this. It seems like there are sphinx extensions to convert images as
needed, e.g.
https://www.sphinx-doc.org/en/master/usage/extensions/imgconverter.html
or
https://github.com/sephalon/sphinxcontrib-svg2pdfconverter
which seems to support inkscape:
https://github.com/sephalon/sphinxcontrib-svg2pdfconverter/blob/master/sphinxcontrib/inkscapeconverter.py


Have you looked into that or not?


> My goal is to progressively replace PNG diagrams with SVG ones:
>    - To get high quality definition output documents, in all output formats
>    - To Have the ability to update diagrams
> I would indeed do this very progressively, a little bit every week,
> not at the expense of other tasks.
>
> Michael Opdenacker (3):
>   Makefile: allow epub and latexpdf outputs to use diagrams from SVG
>     sources
>   conf.py: prefer PNG to SVG in EPUB output
>   overview-manual: SVG diagram for the git workflow
>
>  documentation/.gitignore                      |    2 +
>  documentation/Makefile                        |   29 +-
>  documentation/conf.py                         |    4 +
>  .../development-environment.rst               |    4 +-
>  .../overview-manual/figures/git-workflow.png  |  Bin 26586 -> 0 bytes
>  .../overview-manual/svg/git-workflow.svg      | 1205 +++++++++++++++++
>  6 files changed, 1239 insertions(+), 5 deletions(-)
>  delete mode 100644 documentation/overview-manual/figures/git-workflow.png
>  create mode 100644 documentation/overview-manual/svg/git-workflow.svg
>
> --
> 2.25.1
>
>
> 
>
>

[-- Attachment #2: Type: text/html, Size: 3991 bytes --]