From bfafa9e037044c317783e47a1ca77e8a17aad789 Mon Sep 17 00:00:00 2001 From: Felix Held Date: Fri, 27 Dec 2019 19:18:02 +0100 Subject: [PATCH] Documentation: document non-Docker sphinx installation and usage Also update the known-good versions of the needed tools. Change-Id: I0f63860beb0a8a00360752318236e302c7170977 Signed-off-by: Felix Held Reviewed-on: https://review.coreboot.org/c/coreboot/+/37952 Reviewed-by: Patrick Rudolph Reviewed-by: Paul Menzel Tested-by: build bot (Jenkins) --- .../getting_started/writing_documentation.md | 21 +++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/Documentation/getting_started/writing_documentation.md b/Documentation/getting_started/writing_documentation.md index dc3cd34413..384fc6d1fc 100644 --- a/Documentation/getting_started/writing_documentation.md +++ b/Documentation/getting_started/writing_documentation.md @@ -42,8 +42,25 @@ Please follow this official [guide] to install sphinx. You will also need python-recommonmark for sphinx to be able to handle markdown documentation. -The recommended version is sphinx 1.7.7, sphinx_rtd_theme 0.4.1 and -recommonmark 0.4.0. +Since some Linux distributions don't package every needed sphinx extension, +the installation via pip in a venv is recommended. You'll need these python3 +modules: + +* sphinx +* recommonmark +* sphinx_rtd_theme +* sphinxcontrib-ditaa + +The following combination of versions has been tested: sphinx 2.3.1, +recommonmark 0.6.0, sphinx_rtd_theme 0.4.3 and sphinxcontrib-ditaa 0.7. + +Now change into the `Documentation` folder in the coreboot directory and run +this command in there + + make sphinx + +If no error occurs, you can find the generated HTML documentation in +`Documentation/_build` now. ### Optional