This covers most of the changes that would require action on the part of
the user that I was able to see by scouring the commits. Some of the text
was borrowed from commit messages and edited.
(From yocto-docs rev: 35e9349ba6417765274d7d1ce542e7e6f19dbe26)
Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
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>
This avoids the duplicate heading warnings at the slight expense
of more directory clutter.
(From yocto-docs rev: ef896d71836aa3bd6c926b36976a9c45d5f2ca15)
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>
SPDX headers have been added to each file, and match the headers used
in the DocBook files.
(From yocto-docs rev: 79dbb0007ae24da4a3689a23e921f2a2638757f7)
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>
