@@ -34,16 +34,18 @@ Manual Organization
Here the folders corresponding to individual manuals:
+* brief-yoctoprojectqs - Yocto Project Quick Start
* overview-manual - Yocto Project Overview and Concepts Manual
-* sdk-manual - Yocto Project Software Development Kit (SDK) Developer's Guide.
+* contributor-guide - Yocto Project and OpenEmbedded Contributor Guide
+* ref-manual - Yocto Project Reference Manual
* bsp-guide - Yocto Project Board Support Package (BSP) Developer's Guide
* dev-manual - Yocto Project Development Tasks Manual
* kernel-dev - Yocto Project Linux Kernel Development Manual
-* ref-manual - Yocto Project Reference Manual
-* brief-yoctoprojectqs - Yocto Project Quick Start
* profile-manual - Yocto Project Profiling and Tracing Manual
+* sdk-manual - Yocto Project Software Development Kit (SDK) Developer's Guide.
* toaster-manual - Toaster User Manual
* test-manual - Yocto Project Test Environment Manual
+* migration-guides - Yocto Project Release and Migration Notes
Each folder is self-contained regarding content and figures.
@@ -129,6 +131,10 @@ Also install the "inkscape" package from your distribution.
Inkscape is need to convert SVG graphics to PNG (for EPUB
export) and to PDF (for PDF export).
+Additionally install "fncychap.sty" TeX font if you want to build PDFs. Debian
+and Ubuntu have it in "texlive-latex-extra" package while RedHat distributions
+and OpenSUSE have it in "texlive-fncychap" package for example.
+
To build the documentation locally, run:
$ cd documentation
@@ -271,6 +277,19 @@ websites.
More information can be found here:
https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html.
+For external links, we use this syntax:
+`link text <link URL>`__
+
+instead of:
+`link text <link URL>`_
+
+Both syntaxes work, but the latter also creates a "link text" reference
+target which could conflict with other references with the same name.
+So, only use this variant when you wish to make multiple references
+to this link, reusing only the target name.
+
+See https://stackoverflow.com/questions/27420317/restructured-text-rst-http-links-underscore-vs-use
+
Anchor (<#link>) links are forbidden as they are not checked by Sphinx during
the build and may be broken without knowing about it.
@@ -340,13 +359,16 @@ The sphinx.ext.intersphinx extension is enabled by default
so that we can cross reference content from other Sphinx based
documentation projects, such as the BitBake manual.
-References to the BitBake manual can be done:
+References to the BitBake manual can directly be done:
- With a specific description instead of the section name:
- :ref:`Azure Storage fetcher (az://) <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`
+ :ref:`Azure Storage fetcher (az://) <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`
- With the section name:
- :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax` option
- - Linking to the entire BitBake manual:
- :doc:`BitBake User Manual <bitbake:index>`
+ :ref:`bitbake-user-manual/bitbake-user-manual-intro:usage and syntax` option
+
+If you want to refer to an entire document (or chapter) in the BitBake manual,
+you have to use the ":doc:" macro with the "bitbake:" prefix:
+ - :doc:`BitBake User Manual <bitbake:index>`
+ - :doc:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata`" chapter
Note that a reference to a variable (:term:`VARIABLE`) automatically points to
the BitBake manual if the variable is not described in the Reference Manual's Variable Glossary.
@@ -355,6 +377,11 @@ BitBake manual as follows:
:term:`bitbake:BB_NUMBER_PARSE_THREADS`
+This would be the same if we had identical document filenames in
+both the Yocto Project and BitBake manuals:
+
+ :ref:`bitbake:directory/file:section title`
+
Submitting documentation changes
================================