Hi Mauro,
one more addition: in patch
9fc3a18a94 docs: remove extra conf.py files
the conf.py from SPHINXDIRS has been removed since some latex
stuff was no longer needed. IMO this is not a really good idea,
this patch also remove the individual project titles like:
project = "Core-API Documentation"
and it also removes the:
tags.add("subproject")
which is widly used, e.g.:
.. only:: subproject and html
Indices
=======
* :ref:`genindex`
Anyway: if we do so we can also remove such directives and we can
also remove the 'loadConfig' which was added in
606b9ac81a doc-rst: generic way to build only sphinx sub-folders
Sorry, that I do not have time to prepare a well formed patch.
But I maintain my opinion that we'd better not do that.
-- Markus --
Am 21.04.20 um 12:52 schrieb Markus Heiser:
> 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
> =============
>
