docs: Raise the minimum Sphinx requirement to 2.4.4

Commit 31abfdda6527 (docs: Deprecate use of Sphinx < 2.4.x) in 6.2 added a
warning that support for older versions of Sphinx would be going away.
There have been no complaints, so the time has come. Raise the minimum
Sphinx version to 2.4.4 and clean out some compatibility code that we no
longer need.

Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/874jgs47fq.fsf@meer.lwn.net
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs/sphinx: Explicitly convert Sphinx paths to str

Sphinx 7.2+ is switching to using pathlib.Path
instead of str to represent paths. This fixes the
current deprecation warnings and eventual breakage.
This conversion will be a no-op when using older
Sphinx versions.

Signed-off-by: Oliver Faso <erer1243@gmail.com>
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20230910040811.53046-1-erer1243@gmail.com

docs: kfigure.py: Don't warn of missing PDF converter in 'make htmldocs'

SVG -> PDF conversion is not required in "make htmldocs".
It is pointless to always warn of a missing converter.
Demote the log message in setupTools() to verbose.

For "make pdfdocs" (or "make latexdocs"), promote the dynamic
message of "include SVG raw" to a warn.
Expand the message and recommend installing Inkscape or
ImageMagick.

Fixes: 8ccd05697a9d ("docs: sphinx/kfigure.py: Use inkscape(1) for SVG -> PDF conversion")
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: linux-doc@vger.kernel.org
Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/c80e1481-10d4-7151-fe59-e846259eb0d4@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: sphinx/kfigure.py: Delegate inkscape msg to kernellog.verbose

Depending on its version, distro config, and system-setup type,
inkscape(1) emits various warning messages which are harmless in
command-line uses.

List of such warning messages (incomplete, long ones wrapped):

- Gtk-Message: hh:mm:ss.nnn: Failed to load module "canberra-gtk-module"
- Unable to init server: Could not connect: Connection refused
- Failed to get connection
- ** (inkscape:xxx): CRITICAL **: hh:mm:ss.nnn: dbus_g_proxy_new_for_name:
assertion 'connection != NULL' failed
- ** (inkscape:xxx): CRITICAL **: hh:mm:ss.nnn: dbus_g_proxy_call:
assertion 'DBUS_IS_G_PROXY (proxy)' failed
- ** (inkscape:xxx): CRITICAL **: hh:mm:ss.nnn: dbus_g_connection_register_g_object:
assertion 'connection != NULL' failed
- ** (inkscape:xxx): WARNING **: hh:mm:ss.nnn:
Fonts dir '/usr/share/inkscape/fonts' does not exist and will be ignored.

To avoid unnecessary anxiety, capture the message and output it via
kernellog.verbose or kernellog.warn depending on the exit code.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/e26a7b53-9155-8394-4a31-6006379b65a5@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: sphinx/kfigure.py: Use inkscape(1) for SVG -> PDF conversion

Using convert(1) of ImageMagick for SVG -> PDF conversion results in
PDFs containing raster (bitmap) images which sometimes look blurry.

Ideally speaking, SVG to PDF conversion should retain vector graphics
in SVG.

rsvg-convert(1) can do such conversions with regard to SVG files
generated by dot(1).

Unfortunately, rsvg-convert(1) does not cover some of SVG features
specific to Inkscape.
inkscape(1) of Inkscape naturally covers such SVG features.

So add a route in svg2pdf() so that inkscape(1) is used when it is
available.

Note:
After this change, if you have Inkscape installed, ImageMagick nor
librsvg are not required.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/3eea2a8d-c52d-ee07-cf7b-83784c6f6e4b@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: sphinx/kfigure.py: Add check of 'dot -Tpdf'

To prevent any regression on existing build systems, limit the
fallback of converting DOT -> raster PDF only when both of the
following conditions are met.

o dot(1) doesn't support -Tpdf
o rsvg-convert(1) is not found

While we are here, add kernellog.verbose messages related to
rsvg-convert, 'dot -Tpdf', and 'dot -Tsvg' commands.

Suggested-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/e76f61e1-7366-ba00-b119-8ea6a2499861@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: sphinx/kfigure.py: Use rsvg-convert(1) for DOT -> PDF conversion

On openSUSE, dot(1) command does not support direct PDF output.
On other distros, generated PDF images have unnecessarily wide margins,
especially for small graphs.

By using dot(1) for DOT -> SVG, then rsvg-convert(1) for SVG -> PDF,
more optimal PDF images can be obtained, with the bonus of improved
portability across various distros.

Add rules in kfigure.py so that the above mentioned route is taken
when rsvg-convert(1) is available.

Note that rsvg-convert(1) is recommended by sphinx_pre_install.
So it is most likely that existing systems for building pdfdocs have
rsvg-convert(1) installed.

Note:
SVG features supported by rsvg-convert(1) vary depending on its
version and distro config.
For example, the one found on Ubuntu Bionic (version 2.40.20) does
poor job in rendering some of SVG files drawn by Inkscape.
SVG files generated by dot(1) are converted nicely even with such
old versions of rsvg-convert.

So this change does not affect the quality of such figures in any
way.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/15b56dd3-081a-2469-c3a4-dfc1ca4c6c2d@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Docs: drop Python 2 support

The kernel build system as a whole is dropping support for Python 2, so we
should do the same. The effects are rather small, especially considering
that much of the deleted code was not doing anything under any version of
Python anyway.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Replace HTTP links with HTTPS ones: documentation

Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.

Deterministic algorithm:
For each file:
For each line:
If doesn't contain `\bxmlns\b`:
For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`:
If both the HTTP and HTTPS versions
return 200 OK and serve the same content:
Replace HTTP with HTTPS.

Signed-off-by: Alexander A. Klimov <grandmaster@al2klimov.de>
Link: https://lore.kernel.org/r/20200526060544.25127-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc: Cope with Sphinx logging deprecations

Recent versions of sphinx will emit messages like:

Documentation/sphinx/kerneldoc.py:103:
RemovedInSphinx20Warning: app.warning() is now deprecated.
Use sphinx.util.logging instead.

Switch to sphinx.util.logging to make this unsightly message go away.
Alas, that interface was only added in version 1.6, so we have to add a
version check to keep things working with older sphinxes.

Cc: stable@vger.kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

linux-next: docs-rst: Fix typos in kfigure.py

This patch fixes some spelling typos found in kfigure.py

Signed-off-by: Masanari Iida <standby24x7@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs-rst: automatically convert Graphviz and SVG images

This patch brings scalable figure, image handling and a concept to
embed *render* markups:

* DOT (http://www.graphviz.org)
* SVG

For image handling use the 'image' replacement::

.. kernel-image:: svg_image.svg
:alt: simple SVG image

For figure handling use the 'figure' replacement::

.. kernel-figure:: svg_image.svg
:alt: simple SVG image

SVG image example

Embed *render* markups (or languages) like Graphviz's **DOT** is
provided by the *render* directive.::

.. kernel-render:: DOT
:alt: foobar digraph
:caption: Embedded **DOT** (Graphviz) code.

digraph foo {
"bar" -> "baz";
}

The *render* directive is a concept to integrate *render* markups and
languages, yet supported markups:

* DOT: render embedded Graphviz's **DOT**
* SVG: render embedded Scalable Vector Graphics (**SVG**)

Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Tested-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Tested-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> (v2 - v5)
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de> (v1, v6)
Signed-off-by: Jonathan Corbet <corbet@lwn.net>