Hi Mauro,
Am 21.04.20 um 10:38 schrieb Mauro Carvalho Chehab:
>
> Hi,
>
> While building from v5.7-rc2 + media, I noticed that SPHINXDIRS option
> stopped working.
>
> What happens is that, if we don't pass this option, Sphinx assumes that
> the "absolute" path is "Documentation/". So, include options like this:
>
> .. include:: /ABI/stable/firewire-cdev
> :literal:
>
>
> would be evaluated as Documentation/ABI/stable/firewire-cdev if built
> without SPHINXDIRS. However, if we do SPHINXDIRS=driver-api, then
> the "absolute" patch would be "Documentation/driver-api", causing this
> error:
>
> Sphinx parallel build error:
> docutils.utils.SystemMessage: /devel/v4l/patchwork/Documentation/driver-api/firewire.rst:22: (SEVERE/4) Problems with "include" directive path:
>
> This is specially bad for build jobs (like one we have on jenkins that
> is meant to test media patches), as, due to some Sphinx bug, prevents
> sphinx-build to stop, making the toolset to run forever.
>
> I suspect that some change at conf.py could address the path issue.
>
> I'll try to investigate further.
>
> Just to be 100% sure that this is not some version-specific bad
> behavior, I tested (using the latest patch version) Sphinx from
> version 1.7.9 up to 2.4.4. The same two errors happen on all
> versions.
>
> Markus,
>
> Maybe you may have some idea about how to fix those issues.
>
> The parallel build error would likely require fixing something
> inside Sphinx code, making it abort if it gets a "SEVERE" error.
>
> Regards,
> Mauro
>
I fixed it with the patch shown below. Some words about: The use
of the :doc: rule should be replaced by a :ref:. The path names
of include directives should always relative to the .rst file.
To go further ... with patch below:
$ make SPHINXDIRS="driver-api" htmldocs
shows some " WARNING: undefined label: ..." messages. To close
such links (addressing objects outside of the SPHINXDIR) we need
to activate intersphinx [1].
If we activate intersphinx we have to wait one release cycle to
get a objects.inv file at:
https://www.kernel.org/doc/html/latest/
When the objects.inv file is available, the warnings are
disappear.
If the process of intersphinx is unclear, please ask.
-- Markus --
[1] https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
----
diff --git a/Documentation/driver-api/firewire.rst b/Documentation/driver-api/firewire.rst
index 94a2d7f01d99..67741aeae5e8 100644
--- a/Documentation/driver-api/firewire.rst
+++ b/Documentation/driver-api/firewire.rst
@@ -19,16 +19,16 @@ of kernel interfaces is available via exported symbols in `firewire-core` module
Firewire char device data structures
====================================
-.. include:: /ABI/stable/firewire-cdev
+.. include:: ../ABI/stable/firewire-cdev
:literal:
-.. kernel-doc:: include/uapi/linux/firewire-cdev.h
+.. kernel-doc:: /include/uapi/linux/firewire-cdev.h
:internal:
Firewire device probing and sysfs interfaces
============================================
-.. include:: /ABI/stable/sysfs-bus-firewire
+.. include:: ../ABI/stable/sysfs-bus-firewire
:literal:
.. kernel-doc:: drivers/firewire/core-device.c
diff --git a/Documentation/driver-api/gpio/using-gpio.rst b/Documentation/driver-api/gpio/using-gpio.rst
index dda069444032..f2bd1e72af4e 100644
--- a/Documentation/driver-api/gpio/using-gpio.rst
+++ b/Documentation/driver-api/gpio/using-gpio.rst
@@ -15,7 +15,7 @@ For any kind of mass produced system you want to support, such as servers,
laptops, phones, tablets, routers, and any consumer or office or business goods
using appropriate kernel drivers is paramount. Submit your code for inclusion
in the upstream Linux kernel when you feel it is mature enough and you will get
-help to refine it, see :doc:`../../process/submitting-patches`.
+help to refine it, see :ref:`submittingpatches`.
In Linux GPIO lines also have a userspace ABI.
diff --git a/Documentation/driver-api/ioctl.rst b/Documentation/driver-api/ioctl.rst
index c455db0e1627..ad91db68ba89 100644
--- a/Documentation/driver-api/ioctl.rst
+++ b/Documentation/driver-api/ioctl.rst
@@ -34,7 +34,7 @@ _IO/_IOR/_IOW/_IOWR
type
An 8-bit number, often a character literal, specific to a subsystem
- or driver, and listed in :doc:`../userspace-api/ioctl/ioctl-number`
+ or driver, and listed in :ref:`ioctl numbers`
nr
An 8-bit number identifying the specific command, unique for a give
diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst
index 52bf58417653..09647516ca52 100644
--- a/Documentation/userspace-api/ioctl/ioctl-number.rst
+++ b/Documentation/userspace-api/ioctl/ioctl-number.rst
@@ -1,3 +1,5 @@
+.. _ioctl numbers:
+
=============
Ioctl Numbers
=============
