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

[Simon Glass]

Hi,

On Sun, 24 Jan 2021 at 18:37, Tom Rini <trini at 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 at gmx.de>
> > > > > > > Reviewed-by: Simon Glass <sjg at 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?

Regards,
Simon