diff options
Diffstat (limited to 'documentation/README')
| -rw-r--r-- | documentation/README | 67 |
1 files changed, 59 insertions, 8 deletions
diff --git a/documentation/README b/documentation/README index 6333f0496a..b60472fcbf 100644 --- a/documentation/README +++ b/documentation/README @@ -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. @@ -149,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 ================================== @@ -275,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. @@ -344,13 +387,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. @@ -359,6 +405,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 ================================ |