From mboxrd@z Thu Jan 1 00:00:00 1970 From: Sean Anderson Date: Sun, 24 Jan 2021 19:49:44 -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: <6ed41b1f-3b78-b19a-ce26-5c10f68e0b04@gmail.com> List-Id: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit To: u-boot@lists.denx.de On 1/24/21 7:41 PM, 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/ I use Arch Linux. To compile documentation, I use a virtualenv with Sphinx 2. However, I would like to be able to use the Sphinx included with my distribution. It also took some searching to determine that I needed Sphinx 2 (as I had previously compiled documentation without issue). --Sean > > Best regards > > Heinrich > >> >>> 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? >> >>> Once that is done and the patch is reapplied we must make sure that on >>> gitlab we use Sphinx 3 by moving to a current Ubuntu version. >> >> We'll have to figure out what to do about updating CI, but I'm not sure >> moving the host version is a good idea at this time. >> >