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

[Tom Rini <trini@konsulko.com>]

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.

-- 
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/20210124/966d3da6/attachment.sig>