Hi Heinrich,
On Tue, 26 Jan 2021 at 09:02, Tom Rini trini@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@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@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.
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