[U-Boot] [PATCH 00/50] doc: Shape into useful HTML docs

[Heinrich Schuchardt <xypron.glpk@gmx.de>]

On 7/24/19 4:18 PM, Tom Rini wrote:
> On Wed, Jul 24, 2019 at 10:16:31PM +0800, Bin Meng wrote:
>> Hi Tom,
>>
>> On Wed, Jul 24, 2019 at 10:14 PM Tom Rini <trini@konsulko.com> wrote:
>>>
>>> On Thu, Jul 18, 2019 at 12:33:45AM -0700, Bin Meng wrote:
>>>
>>>> At present there is Sphinx doc build system in U-Boot, however the
>>>> contents are very limited, e.g.: only a few API descriptions like
>>>> EFI, are included.
>>>>
>>>> This series proposes an initial Sphinx doc layout for future extension,
>>>> by converting some of the plain text documentation to reStructuredText
>>>> format and add it to Sphinx TOC tree.
>>>>
>>>> With this series, now we have the following major chapters in our
>>>> U-Boot HTML doc:
>>>>
>>>> - Driver Model
>>>> - U-Boot API documentation
>>>> - Architecture-specific doc
>>>> - Board-specific doc
>>>>
>>>> Board specific documents are put in a vendor subdirectory, just like
>>>> what we have in <src_tree>/board. All x86 & RISC-V board docs are
>>>> converted to reST. A few other board docs are converted too.
>>>>
>>>> Tested by generating the HTML docs, 0 build warnings.
>>>>
>>>> This patch is rebased on https://patchwork.ozlabs.org/patch/1131726/.
>>>>
>>>> @Wolfgang, is it possible to host the Sphinx HTML docs on denx.de?
>>>>
>>>> This series is available at u-boot-x86/doc for testing.
>>>
>>> As a follow-up, please update .gitlab-ci.yml at least to include a run
>>> of "make htmldocs".  If we need to update the Dockerfile to include new
>>> utils we can do that too, thanks!
>>
>> Yes, but I will need some time to study GitLab's .gitlab-ci.yml :)
>>
>> Could that be done later?
>
> Yes, to be clear, I asked for a follow-up as I have this otherwise
> merged locally but can't test it since make htmldocs blows up about a
> lack of required tools that I don't see documented.  Once my current
> pipeline finishes (of other changes) I'll push this.
>

Hello Tom,

the necessary packages for Ubuntu Bionic to run 'make htmldocs' are:

build-essential sphinx-doc python3-sphinx

A warning occurs requesting packages graphviz and imagemagick.

Graphviz is currently not installable via apt-get but as we currently
have no graphics in our documentation you can simply ignore the warnings.

Cf.
https://www.katrinasiegfried.com/single-post/2018/10/24/Installing-GraphViz-on-Linux-Ubuntu-1804LTS

The ReadTheDocs theme can be installed via

git clone https://github.com/readthedocs/sphinx_rtd_theme
cd sphinx_rtd_theme/
sudo apt-get install python3-setuptools
python3 setup.py install

This theme is not really needed but the output looks much nicer.

The generated documentation is available under doc/output/.

Best regards

Heinrich