diff options
Diffstat (limited to 'documentation/README')
| -rw-r--r-- | documentation/README | 150 |
1 files changed, 113 insertions, 37 deletions
diff --git a/documentation/README b/documentation/README index fddf4e706d..b60472fcbf 100644 --- a/documentation/README +++ b/documentation/README @@ -32,28 +32,25 @@ these instances. Manual Organization =================== -Folders exist for individual manuals as follows: - -* sdk-manual - The Yocto Project Software Development Kit (SDK) Developer's Guide. -* bsp-guide - The Yocto Project Board Support Package (BSP) Developer's Guide -* dev-manual - The Yocto Project Development Tasks Manual -* kernel-dev - The Yocto Project Linux Kernel Development Tasks Manual -* ref-manual - The Yocto Project Reference Manual -* brief-yoctoprojectqs - The Yocto Project Quick Start -* profile-manual - The Yocto Project Profile and Tracing Manual -* toaster-manual - The Toaster Manual -* test-manual - The Test Environment Manual +Here the folders corresponding to individual manuals: + +* brief-yoctoprojectqs - Yocto Project Quick Start +* overview-manual - Yocto Project Overview and Concepts Manual +* 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 +* 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. 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 "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. - -In general, the Yocto Project site (https://www.yoctoproject.org) is a great -reference for both information and downloads. +the current versions reside at https://docs.yoctoproject.org. poky.yaml ========= @@ -61,9 +58,16 @@ poky.yaml This file defines variables used for documentation production. The variables are used to define release pathnames, URLs for the published manuals, etc. -template -======== -Contains various templates, fonts, and some old PNG files. +standards.md +============ + +This file specifies some rules to follow when contributing to the documentation. + +template/ +========= + +Contains a template.svg, to make it easier to create consistent +SVG diagrams. Sphinx ====== @@ -88,8 +92,8 @@ documentation. 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 website hosting the Yocto Project documentation, can be found +at: https://docs.yoctoproject.org/. The entire Yocto Project documentation, as well as the BitBake manual, is published on this website, including all previously released @@ -111,13 +115,26 @@ documentation with Python3. Sphinx might be available in your Linux distro packages repositories, however it is not recommended 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). +distro. The recommended method to install the latest versions of Sphinx +and of its required dependencies is to use the Python Package Index (pip). To install all required packages run: $ pip3 install sphinx sphinx_rtd_theme pyyaml +To make sure you always have the latest versions of such packages, you +should regularly run the same command with an added "--upgrade" option: + + $ pip3 install --upgrade sphinx sphinx_rtd_theme pyyaml + +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 @@ -134,6 +151,34 @@ dependencies in a virtual environment: $ pipenv install $ pipenv run make html +Style checking the Yocto Project documentation +============================================== + +The project is starting to use Vale (https://vale.sh/) +to validate the text style. + +To install Vale: + + $ pip install vale + +To run Vale: + + $ make stylecheck + +Link checking the Yocto Project documentation +============================================= + +To fix errors which are not reported by Sphinx itself, +the project uses sphinx-lint (https://github.com/sphinx-contrib/sphinx-lint). + +To install sphinx-lint: + + $ pip install sphinx-lint + +To run sphinx-lint: + + $ make sphinx-lint + Sphinx theme and CSS customization ================================== @@ -164,17 +209,18 @@ The layout of the Yocto Project manuals is organized as follows Book Chapter Section - Section - Section + Subsection + Subsubsection + Subsubsubsection -Here are the heading styles defined in Sphinx: +Here are the heading styles that we use in the manuals: - Book => overline === - Chapter => overline *** - Section => ==== - Section => ---- - Section => ^^^^ - Section => """" or ~~~~ + Book => overline === + Chapter => overline *** + Section => ==== + Subsection => ---- + Subsubsection => ~~~~ + Subsubsubsection => ^^^^ With this proposal, we preserve the same TOCs between Sphinx and Docbook. @@ -259,6 +305,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. @@ -328,12 +387,29 @@ 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 like this: +References to the BitBake manual can directly be done: + - With a specific description instead of the section name: + :ref:`Azure Storage fetcher (az://) <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` + - With the section name: + :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. +However, if you need to bypass this, you can explicitely refer to a description in the +BitBake manual as follows: - See the ":ref:`-D <bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax>`" option -or :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 ================================ |