[PATCH 1/1] doc: update Kernel documentation build system

[Tom Rini <trini@konsulko.com>]

On Tue, Jan 26, 2021 at 04:28:24PM +0100, Heinrich Schuchardt wrote:
> On 25.01.21 02:56, Simon Glass wrote:
> > Hi,
> >
> > On Sun, 24 Jan 2021 at 18:37, Tom Rini <trini@konsulko.com> wrote:
> >>
> >> On Mon, Jan 25, 2021 at 01:41:18AM +0100, Heinrich Schuchardt wrote:
> >>> On 1/25/21 12:59 AM, Tom Rini wrote:
> >>>> On Sun, Jan 24, 2021 at 10:05:27PM +0100, Heinrich Schuchardt wrote:
> >>>>> On 1/23/21 6:53 PM, Tom Rini wrote:
> >>>>>> On Sat, Jan 23, 2021 at 12:46:23PM -0500, Tom Rini wrote:
> >>>>>>> On Fri, Jan 01, 2021 at 01:21:11AM +0100, Heinrich Schuchardt wrote:
> >>>>>>>
> >>>>>>>> Update the docomentation build system according to Linux v5.11-rc1.
> >>>>>>>>
> >>>>>>>> With this patch we can build the HTML documentation using either of
> >>>>>>>> Sphinx 2 and Sphinx 3.
> >>>>>>>>
> >>>>>>>> Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
> >>>>>>>> Reviewed-by: Simon Glass <sjg@chromium.org>
> >>>>>>>
> >>>>>>> Applied to u-boot/master, thanks!
> >>>>>>
> >>>>>> I've had to revert this.  While I caught and fixed up in a semi-logical
> >>>>>> way one duplicate label problem, there's another now that I see, and
> >>>>>> probably many more once I rework that one.  It's unclear as well how
> >>>>>> best to handle these otherwise logical duplicate labels, such as "eMMC"
> >>>>>> in doc/board/microchip/mpfs_icicle.rst for example.
> >>>>>
> >>>>> Sphinx 2 is not available for current Linux distributions. Without this
> >>>>> patch we cannot build with Sphinx 3.
> >>>>
> >>>> We need to be careful when saying "current".  Ubuntu 18.04 is still
> >>>> quite current enough and will be until 2022 (as it doesn't go EOL until
> >>>> 2023).  I'm not sure I can even get Sphinx 3.
> >>>
> >>> Developers will not be able to test the documentation if 'make htmldocs'
> >>> fails on their machines because their distribution does not provide
> >>> Sphinx 2.
> >>>
> >>> The current Ubuntu release is 20.10 and provides Sphinx 3.2.
> >>> https://packages.ubuntu.com/groovy/sphinx-common.
> >>>
> >>> Arch Linux is on Sphinx 3.4.
> >>> https://archlinux.org/packages/community/any/python-sphinx/
> >>
> >> And 18.04 is an LTS that doesn't go EOL until April 2023.  Developers
> >> will not be test their documentation if they don't have Sphinx 3
> >> available.  Either side can do as Sean notes and use venv to provide
> >> whatever, and we need to make the error in that case much clearer.  I
> >> would assume that the "still works with gcc-4.9!" Linux kernel has a bit
> >> clearer of an error out in that case.  If not perhaps they would take a
> >> patch :)
> >>
> >> But much more importantly:
> >>>>> All pages must be deduplicated. Instead of duplicate information
> >>>>> references have to be used.
> >>>>
> >>>> So long as it can be done in a way where documentation reads well still,
> >>>> yes.  For example, how should we re-write the example I mentioned so
> >>>> that "eMMC" isn't duplicated?
> >>
> >> Is what really needs to be solved.  Show me how the document in question
> >> gets updated to read well and not have the duplicated heading message.
> >
> > I agree we have to support Sphinx 2 for a while. So we need both!
> >
> > Minor niggle - is it possible to fix the need for the -w flag? Can the
> > Makefile check the version and pass the correct flags itself?
> 
> Do you mean "-W Turn warnings into errors" which never changed its
> meaning in Sphinx since version 1.0?
> 
> Yes, we want to this flag to reject any patch with broken reStructered text.

So it is not like dtc/gcc/etc where we can do -Wno-some-specific-check,
OK.

-- 
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 659 bytes
Desc: not available
URL: <https://lists.denx.de/pipermail/u-boot/attachments/20210126/3b30a43b/attachment.sig>