On 16/05/2018 14:04, Rob Herring wrote:
On Mon, May 14, 2018 at 6:34 PM, Grant Likely grant.likely@arm.com wrote:
Use Sphinx-doc to generate PDF output from the source text. With Sphinx installed, a PDF version of the document can be generated by typing: 'make latexpdf'
Signed-off-by: Grant Likely grant.likely@arm.com
Hi Rob,
Thanks for the comments. I've already applied this patch, so I'll submit followup fixes.
.gitignore | 1 + Makefile | 20 +++++++ README.rst | 56 +++++++++++++++++++ source/conf.py | 163 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ source/ebbr.rst | 22 ++++++-- 5 files changed, 259 insertions(+), 3 deletions(-) create mode 100644 .gitignore create mode 100644 Makefile create mode 100644 source/conf.py
diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..796b96d --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +/build diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..91bb4be --- /dev/null +++ b/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation
SPDX tags here and other new files?
It's a generated file, so I never thought about adding the tags.
+#
+# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = EBBR +SOURCEDIR = source +BUILDDIR = build
+# Put it first so that "make" without argument is like "make help". +help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)+.PHONY: help Makefile
+# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)\ No newline at end of file
^^^
Fixed in a follow-up patch
diff --git a/README.rst b/README.rst index 1babcf4..57fac8f 100644 --- a/README.rst +++ b/README.rst @@ -13,6 +13,62 @@ expected in September 2018. You can find the current draft text in this repository, but be aware that everything in the draft text is subject to change before an official v1.0 release is published.
+Build Instructions +==================
+Requirements +^^^^^^^^^^^^
+* Sphinx version 1.5 or later: http://sphinx-doc.org/contents.html
Why? DT spec only needs 1.2.3 (or its documentation is out of date).
Just because that's what I tested with. 1.2 will probably work fine.
+* LaTeX (and pdflatex, and various LaTeX packages)
+On Debian and Ubuntu +^^^^^^^^^^^^^^^^^^^^ +::
- # apt-get install python-sphinx texlive texlive-latex-extra libalgorithm-diff-perl \
texlive-humanities texlive-generic-recommended texlive-generic-extra+If the version of python-sphinx installed is too old, then an additional
Specifically, this is not needed on ubuntu 17.10 and later.
I cut and paste from the devicetree-spec repo. Can probably be removed.
+new version can be installed with the Python package installer::
- $ apt-get install python-pip
- $ pip install --user --upgrade Sphinx
- $ export SPHINXBUILD=~/.local/bin/sphinx-build
+Export SPHINXBUILD (see above) if Sphinx was installed with pip --user, then follow Make commands below
+On Mac OS X +^^^^^^^^^^^
+* Install MacTeX_ +* Install pip if you do not have it::
- $ sudo easy_install pip
+* Install Sphinx::
- $ pip install --user --upgrade Sphinx
+.. _MacTeX: http://tug.org/mactex
+Make Targets +^^^^^^^^^^^^
+To generate PDF::
- $ make latexpdf
+To generate hierarchy of HTML pages::
- $ make html
+To generate a single HTML page::
- $ make singlehtml
+Output goes in `./build` subdirectory.
License
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.