Felix Held has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/37952 )
Change subject: Documentation: document non-Docker sphinx installation and usage ......................................................................
Documentation: document non-Docker sphinx installation and usage
Change-Id: I0f63860beb0a8a00360752318236e302c7170977 Signed-off-by: Felix Held felix-coreboot@felixheld.de --- M Documentation/getting_started/writing_documentation.md 1 file changed, 16 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/52/37952/1
diff --git a/Documentation/getting_started/writing_documentation.md b/Documentation/getting_started/writing_documentation.md index dc3cd34..51c248f 100644 --- a/Documentation/getting_started/writing_documentation.md +++ b/Documentation/getting_started/writing_documentation.md @@ -45,6 +45,22 @@ 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 + +Now cd into the Documentation folder and run + + make sphinx + +If no error occurs, you can find the generated HTML documentation in +Documentation/_build now. + ### Optional
Install [sphinx-autobuild] for rebuilding markdown/rst sources on the fly!
Paul Menzel has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37952 )
Change subject: Documentation: document non-Docker sphinx installation and usage ......................................................................
Patch Set 1:
(2 comments)
https://review.coreboot.org/c/coreboot/+/37952/1/Documentation/getting_start... File Documentation/getting_started/writing_documentation.md:
https://review.coreboot.org/c/coreboot/+/37952/1/Documentation/getting_start... PS1, Line 57: Now cd into the Documentation folder and run For people unfamiliar with the command line.
Now, change into the directory `Documentation`, and run
cd Documentation make sphinx
(tab instead of spaces)
https://review.coreboot.org/c/coreboot/+/37952/1/Documentation/getting_start... PS1, Line 62: Documentation/_build Please mark up with ``.
Hello Patrick Rudolph, Christoph Pomaska, Arthur Heymans, Felix Singer, build bot (Jenkins),
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/37952
to look at the new patch set (#2).
Change subject: Documentation: document non-Docker sphinx installation and usage ......................................................................
Documentation: document non-Docker sphinx installation and usage
Change-Id: I0f63860beb0a8a00360752318236e302c7170977 Signed-off-by: Felix Held felix-coreboot@felixheld.de --- M Documentation/getting_started/writing_documentation.md 1 file changed, 17 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/52/37952/2
Felix Held has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37952 )
Change subject: Documentation: document non-Docker sphinx installation and usage ......................................................................
Patch Set 2:
(2 comments)
https://review.coreboot.org/c/coreboot/+/37952/1/Documentation/getting_start... File Documentation/getting_started/writing_documentation.md:
https://review.coreboot.org/c/coreboot/+/37952/1/Documentation/getting_start... PS1, Line 57: Now cd into the Documentation folder and run
For people unfamiliar with the command line. […]
cd Documentation will only work when you're in the root of the coreboot directory; that's why I didn't write that there as full command
https://review.coreboot.org/c/coreboot/+/37952/1/Documentation/getting_start... PS1, Line 62: Documentation/_build
Please mark up with ``.
Done
Felix Singer has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37952 )
Change subject: Documentation: document non-Docker sphinx installation and usage ......................................................................
Patch Set 2: Code-Review+1
Patrick Rudolph has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37952 )
Change subject: Documentation: document non-Docker sphinx installation and usage ......................................................................
Patch Set 3: Code-Review+1
(1 comment)
https://review.coreboot.org/c/coreboot/+/37952/3/Documentation/getting_start... File Documentation/getting_started/writing_documentation.md:
https://review.coreboot.org/c/coreboot/+/37952/3/Documentation/getting_start... PS3, Line 45: The recommended version is sphinx 1.7.7, sphinx_rtd_theme 0.4.1 and merge with lines added below?
Hello Patrick Rudolph, Christoph Pomaska, Angel Pons, Arthur Heymans, Patrick Rudolph, Felix Singer, build bot (Jenkins),
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/37952
to look at the new patch set (#4).
Change subject: Documentation: document non-Docker sphinx installation and usage ......................................................................
Documentation: document non-Docker sphinx installation and usage
Change-Id: I0f63860beb0a8a00360752318236e302c7170977 Signed-off-by: Felix Held felix-coreboot@felixheld.de --- M Documentation/getting_started/writing_documentation.md 1 file changed, 19 insertions(+), 2 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/52/37952/4
Felix Held has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37952 )
Change subject: Documentation: document non-Docker sphinx installation and usage ......................................................................
Patch Set 4:
(1 comment)
https://review.coreboot.org/c/coreboot/+/37952/3/Documentation/getting_start... File Documentation/getting_started/writing_documentation.md:
https://review.coreboot.org/c/coreboot/+/37952/3/Documentation/getting_start... PS3, Line 45: The recommended version is sphinx 1.7.7, sphinx_rtd_theme 0.4.1 and
merge with lines added below?
Done
Hello Patrick Rudolph, Christoph Pomaska, Angel Pons, Arthur Heymans, Patrick Rudolph, Felix Singer, build bot (Jenkins),
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/37952
to look at the new patch set (#5).
Change subject: Documentation: document non-Docker sphinx installation and usage ......................................................................
Documentation: document non-Docker sphinx installation and usage
Change-Id: I0f63860beb0a8a00360752318236e302c7170977 Signed-off-by: Felix Held felix-coreboot@felixheld.de --- M Documentation/getting_started/writing_documentation.md 1 file changed, 19 insertions(+), 2 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/52/37952/5
Paul Menzel has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37952 )
Change subject: Documentation: document non-Docker sphinx installation and usage ......................................................................
Patch Set 5: Code-Review+1
(1 comment)
https://review.coreboot.org/c/coreboot/+/37952/5/Documentation/getting_start... File Documentation/getting_started/writing_documentation.md:
https://review.coreboot.org/c/coreboot/+/37952/5/Documentation/getting_start... PS5, Line 55: recommonmark 0.6.0, sphinx_rtd_theme 0.4.3 and sphinxcontrib-ditaa 0.7. Would be nice in a separate commit, but it’s not that important.
Hello Patrick Rudolph, Christoph Pomaska, Angel Pons, Arthur Heymans, Patrick Rudolph, Paul Menzel, Felix Singer, build bot (Jenkins),
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/37952
to look at the new patch set (#6).
Change subject: Documentation: document non-Docker sphinx installation and usage ......................................................................
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 felix-coreboot@felixheld.de --- M Documentation/getting_started/writing_documentation.md 1 file changed, 19 insertions(+), 2 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/52/37952/6
Felix Held has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37952 )
Change subject: Documentation: document non-Docker sphinx installation and usage ......................................................................
Patch Set 6:
(1 comment)
https://review.coreboot.org/c/coreboot/+/37952/5/Documentation/getting_start... File Documentation/getting_started/writing_documentation.md:
https://review.coreboot.org/c/coreboot/+/37952/5/Documentation/getting_start... PS5, Line 55: recommonmark 0.6.0, sphinx_rtd_theme 0.4.3 and sphinxcontrib-ditaa 0.7.
Would be nice in a separate commit, but it’s not that important.
I only tested generating the documentation with the more recent version and I only changed that part as well, because i was asked to on the previous change set. I'd also consider this being one logical change, since I extended the very lacking documentation to be useful and updated the version numbers to the current ones and verified that it still works. Haven't tested if the old versions work with this installation method; also the current version seems to have one more dependency. I'm not motivated to dive deeper into this bikeshed tbh; just want to provide some useful instructions on how to generate the documentation to be able to write documentation without much trial and error or a docker container setup :/
Patrick Rudolph has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37952 )
Change subject: Documentation: document non-Docker sphinx installation and usage ......................................................................
Patch Set 6: Code-Review+2
Patrick Georgi has submitted this change. ( https://review.coreboot.org/c/coreboot/+/37952 )
Change subject: Documentation: document non-Docker sphinx installation and usage ......................................................................
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 felix-coreboot@felixheld.de Reviewed-on: https://review.coreboot.org/c/coreboot/+/37952 Reviewed-by: Patrick Rudolph siro@das-labor.org Reviewed-by: Paul Menzel paulepanter@users.sourceforge.net Tested-by: build bot (Jenkins) no-reply@coreboot.org --- M Documentation/getting_started/writing_documentation.md 1 file changed, 19 insertions(+), 2 deletions(-)
Approvals: build bot (Jenkins): Verified Paul Menzel: Looks good to me, but someone else must approve Patrick Rudolph: Looks good to me, approved
diff --git a/Documentation/getting_started/writing_documentation.md b/Documentation/getting_started/writing_documentation.md index dc3cd34..384fc6d 100644 --- a/Documentation/getting_started/writing_documentation.md +++ b/Documentation/getting_started/writing_documentation.md @@ -42,8 +42,25 @@ 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
9elements QA has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37952 )
Change subject: Documentation: document non-Docker sphinx installation and usage ......................................................................
Patch Set 7:
Automatic boot test returned (PASS/FAIL/TOTAL): 3/0/3 Emulation targets: EMULATION_QEMU_X86_Q35 using payload TianoCore : SUCCESS : No test failed. EMULATION_QEMU_X86_Q35 using payload SeaBIOS : SUCCESS : No test failed. EMULATION_QEMU_X86_I440FX using payload SeaBIOS : SUCCESS : No test failed.
Please note: This test is under development and might not be accurate at all!