|author||Michael Opdenacker <firstname.lastname@example.org>||2021-03-23 15:45:29 +0100|
|committer||Richard Purdie <email@example.com>||2021-03-23 22:54:55 +0000|
documentation/README minor improvements
- Minor style and spelling fixes - Add some extra details; add missing external link macros and explain where they are defined - Correct where documentation can be found on the Yocto Project website: the "Documentation" tab has been replaced by "Docs" (and it's later shown as uppercase ("DOCS") by the current CSS, but this may change one day. (From yocto-docs rev: ed7b4f318c9ba6cf501f1e551c7a8eb4aaee1396) Signed-off-by: Michael Opdenacker <firstname.lastname@example.org> Signed-off-by: Richard Purdie <email@example.com>
1 files changed, 16 insertions, 11 deletions
diff --git a/documentation/README b/documentation/README
index 15623ce6c1..159ec94608 100644
@@ -47,7 +47,7 @@ Folders exist for individual manuals as follows:
Each folder is self-contained regarding content and figures.
If you want to find HTML versions of the Yocto Project manuals on the web,
-go to https://www.yoctoproject.org and click on the "Documentation" tab. From
+go to https://www.yoctoproject.org and click on the "Docs" tab. From
there you have access to archived documentation from previous releases, current
documentation for the latest release, and "Docs in Progress" for the release
currently being developed.
@@ -91,13 +91,13 @@ Yocto Project documentation website
A new website has been created to host the Yocto Project
documentation, it can be found at: https://docs.yoctoproject.org/.
-The entire Yocto Project documentation, as well as the BitBake manual
+The entire Yocto Project documentation, as well as the BitBake manual,
is published on this website, including all previously released
versions. A version switcher was added, as a drop-down menu on the top
of the page to switch back and forth between the various versions of
the current active Yocto Project releases.
-Transition pages have been added (as rst file) to show links to old
+Transition pages have been added (as rst files) to show links to old
versions of the Yocto Project documentation with links to each manual
generated with DocBook.
@@ -109,7 +109,7 @@ obvious reasons, we will only support building the Yocto Project
documentation with Python3.
Sphinx might be available in your Linux distro packages repositories,
-however it is not recommend using distro packages, as they might be
+however it is not recommend to use distro packages, as they might be
old versions, especially if you are using an LTS version of your
distro. The recommended method to install Sphinx and all required
dependencies is to use the Python Package Index (pip).
@@ -185,7 +185,7 @@ Sphinx has a glossary directive. From
This directive must contain a reST definition list with terms and
- definitions. The definitions will then be referencable with the
+ definitions. It's then possible to refer to each definition through the
@@ -206,7 +206,7 @@ however there are important shortcomings. For example they cannot be
used/nested inside code-block sections.
A Sphinx extension was implemented to support variable substitutions
-to mimic the DocBook based documentation behavior. Variabes
+to mimic the DocBook based documentation behavior. Variable
substitutions are done while reading/parsing the .rst files. The
pattern for variables substitutions is the same as with DocBook,
@@ -237,14 +237,14 @@ Note directive
Sphinx has a builtin 'note' directive that produces clean Note section
in the output file. There are various types of directives such as
"attention", "caution", "danger", "error", "hint", "important", "tip",
-"warning", "admonition" that are supported, and additional directive
+"warning", "admonition" that are supported, and additional directives
can be added as Sphinx extension if needed.
The Yocto Project documentation has many figures/images. Sphinx has a
-'figure' directive which is straight forward to use. To include a
+'figure' directive which is straightforward to use. To include a
figure in the body of the documentation:
.. image:: figures/YP-flow-diagram.png
@@ -262,7 +262,7 @@ https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html.
-The following extension is enabed by default:
+The following extension is enabled by default:
@@ -271,7 +271,7 @@ autosectionlabel_prefix_document is enabled by default, so that we can
insert references from any document.
For example, to insert an HTML link to a section from
Please check this :ref:`manual/intro:Cross-References to Locations in the Same Document`
@@ -294,7 +294,8 @@ Extlinks
The sphinx.ext.extlinks extension is enabled by default
-and it is configured with:
+and it is configured with the 'extlinks' definitions in
+the 'documentation/conf.py' file:
'yocto_home': ('https://yoctoproject.org%s', None),
'yocto_wiki': ('https://wiki.yoctoproject.org%s', None),
@@ -306,6 +307,10 @@ and it is configured with:
'yocto_git': ('https://git.yoctoproject.org%s', None),
'oe_home': ('https://www.openembedded.org%s', None),
'oe_lists': ('https://lists.openembedded.org%s', None),
+ 'oe_git': ('https://git.openembedded.org%s', None),
+ 'oe_wiki': ('https://www.openembedded.org/wiki%s', None),
+ 'oe_layerindex': ('https://layers.openembedded.org%s', None),
+ 'oe_layer': ('https://layers.openembedded.org/layerindex/branch/master/layer%s', None),
It creates convenient shortcuts which can be used throughout the
documentation rst files, as: