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? Regards, Simon
