The release notes are currently hidden in the welcome page, under the
"Release Manuals" section, but these changelogs/migration guides are not
release manuals per say. Move them out of the "Release Manuals" section
under their own "Release Information" section, and make them appear as a
"Release Notes and Migration Guides" section in the welcome page.
(From yocto-docs rev: 67a69f9133434129e404990d2b8a5405343580a0)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
(cherry picked from commit f68f97ee4ee9b444a853569cdbe3c307d2521677)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Paul Barker <paul@pbarker.dev>
This is how the documentation manual is called in the external BitBake
documentation so call it that way. Moreover this aligns better with the
other subsections of the "Manuals" section.
(From yocto-docs rev: a9f1e03127db221ef942875e6e35c1fe5da51e0e)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
(cherry picked from commit 77d257b88861ed690e19e5d03b6f353dfaeb9a82)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Paul Barker <paul@pbarker.dev>
These two links contain more introductory resources to the project and
are external to yocto-docs, but currently break the flow of the
introduction:
- The "Yocto Project Technical Overview" from https://www.yoctoproject.org
is essentially the same as our "Introducing the Yocto Project" section
of the Overview and Concepts manual but with less details.
- The Tips and Tricks wiki page contains a lot of old and obsolete
information, and the wiki is bound to be deprecated at some point.
Additionally, hide them from the sidebar by not including them in a
toctree.
(From yocto-docs rev: ddced6aa15828cfc127e5678ff2e8f64087d250a)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
(cherry picked from commit a23f8a921a56ded065bf94bc52e26f280e83c949)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Paul Barker <paul@pbarker.dev>
The Overview and Concepts manual contains introductory content which
feels like it should rather be in the first section of the welcome page,
rather than the "Manuals" section. Moreover, this section does not feel
like a manual either, so rename the section title to "Overview and
Concepts". Keep the "-manual" suffix to the directory name to avoid
breaking links, though.
(From yocto-docs rev: f1ab418602aefbde6ca46cfe01ee0695a9c91d65)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
(cherry picked from commit 62b982ca545441657491f4d8553144cef7cb3185)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Paul Barker <paul@pbarker.dev>
In many project, contributing sections are usually separate from the
technical documentation and put to the forefront. Let's follow this in
yocto-docs by creating a dedicated section for it on the main page.
(From yocto-docs rev: d80385c1c8221d7d6a11cfdeb504000d7385d44d)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
(cherry picked from commit 8a20261c231c2bda8be6eea2bbefee19b49cf35d)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Paul Barker <paul@pbarker.dev>
The homepage of the Yocto Project documentation currently has no
introduction and only displays the table of contents. Inspired by
https://docs.kernel.org, provide a short introduction to the
documentation and also precede each section with a short sentence about
what the section contains.
The section titles are voluntarily duplicated in the document itself and
in the toctree directive, so that the sidebar still contains them, and we
can have text between the section titles and the toctree content.
However this also duplicates the title in the document itself, so add
CSS directive in our customization file to hide the duplicates.
Note that these titles do not show in the PDF and ePub outputs as those
are generated differently.
(From yocto-docs rev: 378360de3dab9b6f349bac852eff645ab0066093)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
(cherry picked from commit 976ee1e250af67b944521b0446c255c88e57db07)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Paul Barker <paul@pbarker.dev>
Fix the title and link so it goes directly to the
Technical Overview.
(From yocto-docs rev: 1ba3a389b47188b6c664ae3a0bee7ca70e462650)
Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
(cherry picked from commit 0143b586572e15cac438f0fa6f3c1e7446597020)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Paul Barker <paul@pbarker.dev>
The current security-related documentation is a bit hard to find and
hidden within the development manual. However these are processes that
are not part of a development task but is rather a vulnerability
reporting process.
Create a new "Security" section in the documentation to gather this
information. This will be directly visible in the sidebar when opening
the documentation.
Split the previous security-subjects.rst document into 2 documents:
- security-team.rst: defines the roles of the security teams and its
members.
- reporting-vulnerabilities.rst: guide to report vulnerabilities to the
security team.
The plan is to backport these documents to active releases. As a
consequence, this section should be free of instructions and information
that only make sense for a specific release. It should _not_ contain
documents on how to enable security features with Yocto on target
devices, this is unrelated and can be left in the development manual
(for example: dev-manual/vulnerabilities.rst to deal with CVEs).
(From yocto-docs rev: 80556704f8b60b5bf903da497909cfda7dd1b28b)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
(cherry picked from commit 81e14ca2d5cff9e2104c556655144b069633790c)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
These files are placed in the _static directory during publish. Note
that Sphinx does not complain if files do not exist during compilation
(since they are copied at the end). This is why this was used instead of
the ":download:" role.
(From yocto-docs rev: a422a2f4fe452d6f01685717961f6acdf09217de)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
(cherry picked from commit 38aa55418426227203fe3a106fa1e85494a57c12)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Steve Sakoman <steve@sakoman.com>
Starting from the original contents of dev-manual/changes.rst
and from text contributed by Richard Purdie.
(From yocto-docs rev: 55587d9dd009cbc92273376e0f7665b2d574d280)
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Only done for release 3.4 and 3.4.1 so far.
Release notes are kept under the migration-guides/ directory for
the moment, for easier reviewing.
(From yocto-docs rev: b311070d866cf4ab51c72ff3ac7bc41ea3e932cb)
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This makes the reference manual much lighter by moving
the migration guides to a separate document.
The migration guides are also reordered from last to first,
and they appear directly in the left bar, making them easier
to find in the documentation.
(From yocto-docs rev: 5121b86ee97eb62a0c69c9ad1fc0e3fabbe3e934)
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
The 'megamanuel' can be selected using the drop down menu on the
documentation website. It was reported it is confusing to have it on
the main page (and in the left side bar) as well. Let's remove it.
(From yocto-docs rev: 593898dc4a4695395856ea481b58cc5092ed3263)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Reviewed-by: Quentin Schulz <foss@0leil.net>
Tested-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
The top level index file includes a link to the Bitbake
documentation. This link is static, however the location of the
Bitbake documentation depends on the intersphinx configuration. As
such, when looking at an old YP docs release, the link to the bitbake
documentation is always the same (and wrong).
Since we cannot use a cross reference in a toc index, this patch
creates an intermediate page for bitbake documentation, and in that
page we insert the right link to the bibtake documentation
(e.g. :doc:`bitbake:index`) which will be adjusted dynamically based
on intersphinx config.
(From yocto-docs rev: 4f7f451df266a307b34bf145b29291ca85eb882f)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Tested-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
It is more common to call the top level document index.rst. This is
what this patch is doing, along with all required references fixup.
(From yocto-docs rev: 2cea7fbba9210479fc0387d7e1b80da9885558f0)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
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>
The following changes were required after a review of trademark and
branding guidelines:
1. add (R) to 'Yocto Project' on the top left (above the logo)
2. Fix up the capitalization of the main page title
3. Add the copyright/legal blurb at the bottom of the page
For 3. it turned out to be simpler to override the whole footer.html
template, and maintain our own version. Also I took the liberty to
remove the 'next' and 'previous' buttons since I believe they are not
especially useful, given the navigation bar on the left side.
Reported-by: Tracey Erway <tracey.m.erway@intel.com>
(From yocto-docs rev: 6bae1372218e0b10258e4fa6fef72fc1708a329c)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Correct the bitbake and megamanual URLs.
(From yocto-docs rev: 9da83688584f891d9a1fa363bbf073ab7ba0aad7)
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This page is currently a static web page in the Yocto project website,
in the docs section. While we are converting the whole YP docs into
its own website, let's convert this file as well.
(From yocto-docs rev: 0985ac0570c63e5ac8c4329155ed77f71f56f069)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This page is currently a static web page in the Yocto project website,
in the docs section. While we are converting the whole YP docs into
its own website, let's convert this file as well.
(From yocto-docs rev: 1d4db1f776cdb775f79cd5e2089da01e0d9c43ea)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Enhance the sphinx experience/nagivation with:
* Remove the pointless looking parts of breadcrumb navigtation
* Add a document type switcher to the breadcrumb navigation
* Add a version selection switch to the breadcrumb navigation
(From yocto-docs rev: 1823624bdb9ea002d44c9e6d0fd4cd662bff36ad)
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Whenever a TOC follows a title/heading, a blank line is missing. So
let's add it explicitely.
(From yocto-docs rev: 600b6fe7837dd817d32350e1a45431bdcfe8ebbd)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Clean up the top level docs index to refer to all the manuals
with decent titles/links/layout and match the current website docs
page links.
(From yocto-docs rev: 45138057bf9446dfca7bf1ddef97104df57abe76)
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>
Used sphinx-quickstart to generate top level config and
Makefile.sphinx, to allow side by side DocBook and Sphinx
co-existence.
(From yocto-docs rev: 01dd5af7954e24552aca022917669b27bb0541ed)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
