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

[Simon Glass]

Hi Heinrich,

On Tue, 26 Jan 2021 at 09:02, Tom Rini <trini at konsulko.com> wrote:
>
> 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 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?
> >
> > 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.
>

Really what I am looking for is being able to build with version 2 or
3 without any problems, rather than requiring v3, or requiring
removing -w . Is that what we will end up with?

Regards,
Simon