Hi Heinrich, On Tue, 26 Jan 2021 at 09:02, Tom Rini <[email protected]> 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 <[email protected]> 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 <[email protected]> > > >>>>>>>> Reviewed-by: Simon Glass <[email protected]> > > >>>>>>> > > >>>>>>> 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
