When the license identifier tags were added, an incorrect string was used
and the Share-Alike clause was lost. Fix this to match the license
description in the files and add back the lost piece (its clear from
the history it should be there)
(From yocto-docs rev: 8d30c3d792755a7bfdb74b331dad98f51d3516af)
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Before the move to Sphinx, it used to be possible to get a direct link to a
variable from the term glossary. It is very useful when pointing people to
a specific variable when manually looking for it in the glossary.
Let's add this "feature" back.
(From yocto-docs rev: 9e468274eaad270efd5f50e58a523798fcb8097e)
Signed-off-by: Quentin Schulz <foss@0leil.net>
Reviewed-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Since the move to sphinx, variables aren't linked with var- anchors but
term-.
Let's fix that so clicking on a letter will bring to the correct variable
in the page.
(From yocto-docs rev: 07718faa04a8b121be004afbc23b4c338f669413)
Signed-off-by: Quentin Schulz <foss@0leil.net>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This documents the variables used to create keys for
signing fitImage.
(From yocto-docs rev: 7d0407249907259b59191e3759a3b140d30d993e)
Signed-off-by: Usama Arif <usama.arif@arm.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
IMAGE_EFI_BOOT_FILES created to help differentiate files needed between
bootimg-efi and bootimg-partition when creating the installer/.wic file.
(From yocto-docs rev: 3430e56aaa8a528a062af534610dc60346347947)
Signed-off-by: Khairul Rohaizzat Jamaluddin <khairul.rohaizzat.jamaluddin@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
In this commit: 3aeca3b342e5 (ref-manual: Add documentation for
kernel-fitimage), we added a few terms in the glossary, in the docbook
xml file. However there were a few issues in the conversion to sphinx
which needed to be fixed (missed terms, typo, and wrong placement).
(From yocto-docs rev: 968efa8275e30350cead66613d01f491ee61be4d)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Use intersphinx extension to replace links to the Bitbake manual with
proper cross references.
(From yocto-docs rev: 458a6e540a2286ac838812d802306806f77b885c)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Using the intersphinx extension, we can refer to terms in the Bitbake
manual using :term:`bitbake:FOO`. This patch implements that, mostly
using the following regexp:
line = re.sub("`+(\w+)`* <(\&YOCTO_DOCS_BB_URL;)?#var(-bb)?-\\1>`__",
":term:`bitbake:\\1`",
line)
And a handful of manual fixup.
(From yocto-docs rev: d2ed9117fffceb756c4a8f3cb6d39363a271d6d9)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
When an hyperlink should be display in the output, there is no need to
any specific syntax or marker, the parser finds links and mail
addresses in ordinary text. Somehow the conversion from pandoc
generated wrong output in the form: ` <link>`__. This patch is
generated using the following Python regexp:
line = re.sub("` <(https?://.*)>`__",
"\\1",
line)
(From yocto-docs rev: a35d735a74425dff34c63c086947624467658c40)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
In DocBook, variables are used to create custom links (note that it is
not consistent everywhere, since some web addresses are still
hardcoded), such as YOCTO_HOME_URL, YOCTO_GIT_URL, YOCTO_WIKI_URL,
YOCTO_BUGS_URL and YOCTO_DL_URL..
In Sphinx they are replaced with extlinks.
(From yocto-docs rev: d25f3095a9d29a3355581d0743f27b2a423ad580)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Some links were not found by the regexp, especially because of they
are spanning across multiple lines. This patch is a manual fixup for
these patterns.
(From yocto-docs rev: 7a5cf8b372903d959d4a1f0882e6198f31f3cba5)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Some term links have custom 'text', and require manual update, since
they were not caught by the generic Python regexp.
(From yocto-docs rev: 519355ba9daf7630e8d477b2f6f511be51fd8b2e)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Many of the internal links were not converted probably from DocBook
using pandoc. After looking at the various patterns, the follow series
of 'naive' Python regexp were used to perform some additional
automatic conversion.
Also, since we rely on built-in glossary, all links to terms need to
use the sphinx :term: syntax.
This commit is generated using the following Python series of regexp:
line = re.sub("`+(\w+)`* <(\&YOCTO_DOCS_REF_URL;)?#var-\\1>`__",
":term:`\\1`",
line)
line = re.sub("`+do_([a-z_]+)`* <(\&YOCTO_DOCS_REF_URL;)?#ref-tasks-\\1>`__",
":ref:`ref-tasks-\\1`",
line)
line = re.sub("`+([a-z_\-\*\.]+).bbclass`* <(\&YOCTO_DOCS_REF_URL;)?#ref-classes-\\1>`__",
":ref:`\\1.bbclass <ref-classes-\\1>`",
line)
line = re.sub("`+([a-z_\-\*\.]+)`* <(\&YOCTO_DOCS_REF_URL;)?#ref-classes-\\1>`__",
":ref:`\\1 <ref-classes-\\1>`",
line)
line = re.sub("`Source Directory <(\&YOCTO_DOCS_REF_URL;)?#source-directory>`__",
":term:`Source Directory`",
line)
line = re.sub("`Build Directory <(\&YOCTO_DOCS_REF_URL;)?#build-directory>`__",
":term:`Build Directory`",
line)
line = re.sub("`Metadata <(\&YOCTO_DOCS_REF_URL;)?#metadata>`__",
":term:`Metadata`",
line)
line = re.sub("`BitBake <(\&YOCTO_DOCS_REF_URL;)?#bitbake-term>`__",
":term:`BitBake`",
line)
line = re.sub("`Images <(\&YOCTO_DOCS_REF_URL;)?#ref-images>`__",
":ref:`ref-manual/ref-images:Images`",
line)
line = re.sub("`Classes <(\&YOCTO_DOCS_REF_URL;)?#ref-classes>`__",
":ref:`ref-manual/ref-classes:Classes`",
line)
line = re.sub("`workspace <(\&YOCTO_DOCS_REF_URL;)?#devtool-the-workspace-layer-structure>`__",
":ref:`devtool-the-workspace-layer-structure`",
line)
line = re.sub("`Open-?Embedded b?B?uild s?S?ystem <(\&YOCTO_DOCS_REF_URL;)?#build-system-term>`__",
":term:`OpenEmbedded Build System`",
line)
line = re.sub("`(OpenEmbedded-Core )?(\(?OE-Core\)? )?<(\&YOCTO_DOCS_REF_URL;)?#oe-core>`__",
":term:`OpenEmbedded-Core (OE-Core)`",
line)
It won't catch multiline strings, but it catches a very large number
of occurences!
(From yocto-docs rev: 3f537d17de5b1fb76ba3bee196481984a4826378)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Using the builting glossary is well suited for the Yocto Project
'terms' section. Conveniently, all terms will also be added in the
global index.
While converting this to a glossary, also fixed up some content which
was not properly converted by pandoc (such as codeblock sections, or
references in between terms).
(From yocto-docs rev: fce1d16eac1a92f3c6b7bfc74600197b5cb668a2)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Sphinx has a glossary directive. From the documentation:
This directive must contain a reST definition list with terms and
definitions. The definitions will then be referencable with the 'term'
role.
So anywhere in *any* manual, we can do :term:`VAR` to refer to an item
from the glossary, and create a link.
An HTML anchor is created for each term in the glossary, and can be
accessed as:
<link>/ref-variables.html#term-<NAME>
To convert to a glossary, we needed proper indentation (e.g. added 3
spaces to each line)
(From yocto-docs rev: af16cc4233ae9672698cf2fbb7bf0a78e461122e)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is autogenerated pandoc to generate an inital set
of reST files based on DocBook XML files.
A .rst file is generated for each .xml files in all manuals with this
command:
cd <manual>
for i in *.xml; do \
pandoc -f docbook -t rst --shift-heading-level-by=-1 \
$i -o $(basename $i .xml).rst \
done
The conversion was done with: pandoc 2.9.2.1-91 (Arch Linux).
Also created an initial top level index file for each document, and
added all 'books' to the top leve index.rst file.
The YP manuals layout is organized as:
Book
Chapter
Section
Section
Section
Sphinx uses section headers to create the document structure.
ReStructuredText defines sections headers like that:
To break longer text up into sections, you use section headers. These
are a single line of text (one or more words) with adornment: an
underline alone, or an underline and an overline together, in dashes
"-----", equals "======", tildes "~~~~~~" or any of the
non-alphanumeric characters = - ` : ' " ~ ^ _ * + # < > that you feel
comfortable with. An underline-only adornment is distinct from an
overline-and-underline adornment using the same character. The
underline/overline must be at least as long as the title text. Be
consistent, since all sections marked with the same adornment style
are deemed to be at the same level:
Let's define the following convention when converting from Docbook:
Book => overline === (Title)
Chapter => overline *** (1.)
Section => ==== (1.1)
Section => ---- (1.1.1)
Section => ~~~~ (1.1.1.1)
Section => ^^^^ (1.1.1.1.1)
During the conversion with pandoc, we used --shift-heading-level=-1 to
convert most of DocBook headings automatically. However with this
setting, the Chapter header was removed, so I added it back
manually. Without this setting all headings were off by one, which was
more difficult to manually fix.
At least with this change, we now have the same TOC with Sphinx and
DocBook.
(From yocto-docs rev: 3c73d64a476d4423ee4c6808c685fa94d88d7df8)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
