summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMichael Opdenacker <michael.opdenacker@bootlin.com>2021-03-23 14:45:29 (GMT)
committerRichard Purdie <richard.purdie@linuxfoundation.org>2021-03-23 22:54:55 (GMT)
commitc6483187f96c6d21b7129ad78de3ff976fbe5970 (patch)
tree00d793d3361e1044b4825db4a184388ac62c4f43
parent6c9829385ecf78d3dae295cf8a010197d0f87327 (diff)
downloadpoky-c6483187f96c6d21b7129ad78de3ff976fbe5970.tar.gz
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 <michael.opdenacker@bootlin.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/README27
1 files changed, 16 insertions, 11 deletions
diff --git a/documentation/README b/documentation/README
index 15623ce..159ec94 100644
--- a/documentation/README
+++ b/documentation/README
@@ -47,7 +47,7 @@ Folders exist for individual manuals as follows:
47Each folder is self-contained regarding content and figures. 47Each folder is self-contained regarding content and figures.
48 48
49If you want to find HTML versions of the Yocto Project manuals on the web, 49If you want to find HTML versions of the Yocto Project manuals on the web,
50go to https://www.yoctoproject.org and click on the "Documentation" tab. From 50go to https://www.yoctoproject.org and click on the "Docs" tab. From
51there you have access to archived documentation from previous releases, current 51there you have access to archived documentation from previous releases, current
52documentation for the latest release, and "Docs in Progress" for the release 52documentation for the latest release, and "Docs in Progress" for the release
53currently being developed. 53currently being developed.
@@ -91,13 +91,13 @@ Yocto Project documentation website
91A new website has been created to host the Yocto Project 91A new website has been created to host the Yocto Project
92documentation, it can be found at: https://docs.yoctoproject.org/. 92documentation, it can be found at: https://docs.yoctoproject.org/.
93 93
94The entire Yocto Project documentation, as well as the BitBake manual 94The entire Yocto Project documentation, as well as the BitBake manual,
95is published on this website, including all previously released 95is published on this website, including all previously released
96versions. A version switcher was added, as a drop-down menu on the top 96versions. A version switcher was added, as a drop-down menu on the top
97of the page to switch back and forth between the various versions of 97of the page to switch back and forth between the various versions of
98the current active Yocto Project releases. 98the current active Yocto Project releases.
99 99
100Transition pages have been added (as rst file) to show links to old 100Transition pages have been added (as rst files) to show links to old
101versions of the Yocto Project documentation with links to each manual 101versions of the Yocto Project documentation with links to each manual
102generated with DocBook. 102generated with DocBook.
103 103
@@ -109,7 +109,7 @@ obvious reasons, we will only support building the Yocto Project
109documentation with Python3. 109documentation with Python3.
110 110
111Sphinx might be available in your Linux distro packages repositories, 111Sphinx might be available in your Linux distro packages repositories,
112however it is not recommend using distro packages, as they might be 112however it is not recommend to use distro packages, as they might be
113old versions, especially if you are using an LTS version of your 113old versions, especially if you are using an LTS version of your
114distro. The recommended method to install Sphinx and all required 114distro. The recommended method to install Sphinx and all required
115dependencies is to use the Python Package Index (pip). 115dependencies is to use the Python Package Index (pip).
@@ -185,7 +185,7 @@ Sphinx has a glossary directive. From
185https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary: 185https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary:
186 186
187 This directive must contain a reST definition list with terms and 187 This directive must contain a reST definition list with terms and
188 definitions. The definitions will then be referencable with the 188 definitions. It's then possible to refer to each definition through the
189 [https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-term 189 [https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-term
190 'term' role]. 190 'term' role].
191 191
@@ -206,7 +206,7 @@ however there are important shortcomings. For example they cannot be
206used/nested inside code-block sections. 206used/nested inside code-block sections.
207 207
208A Sphinx extension was implemented to support variable substitutions 208A Sphinx extension was implemented to support variable substitutions
209to mimic the DocBook based documentation behavior. Variabes 209to mimic the DocBook based documentation behavior. Variable
210substitutions are done while reading/parsing the .rst files. The 210substitutions are done while reading/parsing the .rst files. The
211pattern for variables substitutions is the same as with DocBook, 211pattern for variables substitutions is the same as with DocBook,
212e.g. `&VAR;`. 212e.g. `&VAR;`.
@@ -237,14 +237,14 @@ Note directive
237Sphinx has a builtin 'note' directive that produces clean Note section 237Sphinx has a builtin 'note' directive that produces clean Note section
238in the output file. There are various types of directives such as 238in the output file. There are various types of directives such as
239"attention", "caution", "danger", "error", "hint", "important", "tip", 239"attention", "caution", "danger", "error", "hint", "important", "tip",
240"warning", "admonition" that are supported, and additional directive 240"warning", "admonition" that are supported, and additional directives
241can be added as Sphinx extension if needed. 241can be added as Sphinx extension if needed.
242 242
243Figures 243Figures
244======= 244=======
245 245
246The Yocto Project documentation has many figures/images. Sphinx has a 246The Yocto Project documentation has many figures/images. Sphinx has a
247'figure' directive which is straight forward to use. To include a 247'figure' directive which is straightforward to use. To include a
248figure in the body of the documentation: 248figure in the body of the documentation:
249 249
250 .. image:: figures/YP-flow-diagram.png 250 .. image:: figures/YP-flow-diagram.png
@@ -262,7 +262,7 @@ https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html.
262References 262References
263========== 263==========
264 264
265The following extension is enabed by default: 265The following extension is enabled by default:
266sphinx.ext.autosectionlabel 266sphinx.ext.autosectionlabel
267(https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html). 267(https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html).
268 268
@@ -271,7 +271,7 @@ autosectionlabel_prefix_document is enabled by default, so that we can
271insert references from any document. 271insert references from any document.
272 272
273For example, to insert an HTML link to a section from 273For example, to insert an HTML link to a section from
274documentaion/manual/intro.rst, use: 274documentation/manual/intro.rst, use:
275 275
276 Please check this :ref:`manual/intro:Cross-References to Locations in the Same Document` 276 Please check this :ref:`manual/intro:Cross-References to Locations in the Same Document`
277 277
@@ -294,7 +294,8 @@ Extlinks
294 294
295The sphinx.ext.extlinks extension is enabled by default 295The sphinx.ext.extlinks extension is enabled by default
296(https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html#use-the-external-links-extension), 296(https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html#use-the-external-links-extension),
297and it is configured with: 297and it is configured with the 'extlinks' definitions in
298the 'documentation/conf.py' file:
298 299
299 'yocto_home': ('https://yoctoproject.org%s', None), 300 'yocto_home': ('https://yoctoproject.org%s', None),
300 'yocto_wiki': ('https://wiki.yoctoproject.org%s', None), 301 'yocto_wiki': ('https://wiki.yoctoproject.org%s', None),
@@ -306,6 +307,10 @@ and it is configured with:
306 'yocto_git': ('https://git.yoctoproject.org%s', None), 307 'yocto_git': ('https://git.yoctoproject.org%s', None),
307 'oe_home': ('https://www.openembedded.org%s', None), 308 'oe_home': ('https://www.openembedded.org%s', None),
308 'oe_lists': ('https://lists.openembedded.org%s', None), 309 'oe_lists': ('https://lists.openembedded.org%s', None),
310 'oe_git': ('https://git.openembedded.org%s', None),
311 'oe_wiki': ('https://www.openembedded.org/wiki%s', None),
312 'oe_layerindex': ('https://layers.openembedded.org%s', None),
313 'oe_layer': ('https://layers.openembedded.org/layerindex/branch/master/layer%s', None),
309 314
310It creates convenient shortcuts which can be used throughout the 315It creates convenient shortcuts which can be used throughout the
311documentation rst files, as: 316documentation rst files, as: