[PATCH 1/1] doc: update Kernel documentation build system

[Sean Anderson]

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 <xypron.glpk at gmx.de>
>>>>>> Reviewed-by: Simon Glass <sjg at 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/

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.
>>
>