From mboxrd@z Thu Jan 1 00:00:00 1970 From: Tom Rini Date: Sun, 24 Jan 2021 20:37:32 -0500 Subject: [PATCH 1/1] doc: update Kernel documentation build system In-Reply-To: <54b80792-8745-fa48-310b-efea4538aa6a@gmx.de> References: <20210101002111.43545-1-xypron.glpk@gmx.de> <20210123174623.GR9782@bill-the-cat> <20210123175352.GX9782@bill-the-cat> <20210124235932.GA7530@bill-the-cat> <54b80792-8745-fa48-310b-efea4538aa6a@gmx.de> Message-ID: <20210125013732.GB7530@bill-the-cat> List-Id: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit To: u-boot@lists.denx.de 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 > > > > > > Reviewed-by: Simon Glass > > > > > > > > > > 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. -- Tom -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 659 bytes Desc: not available URL: