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 <tr...@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.g...@gmx.de> > >>>>>>>> Reviewed-by: Simon Glass <s...@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
signature.asc
Description: PGP signature