diff options
author | Nicolas Dechesne <nicolas.dechesne@linaro.org> | 2020-11-20 20:17:33 +0100 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2021-01-04 10:55:00 +0000 |
commit | fa0cb4d34b1073f215fa3c680f2316208739d53d (patch) | |
tree | ba89c1f4289fd6456af4409a6a19caf6548dfb9c /documentation/README | |
parent | a038e58f3cd82c56102444bdc5ac76c9f1550a0d (diff) | |
download | poky-fa0cb4d34b1073f215fa3c680f2316208739d53d.tar.gz |
sphinx: import docs
The Yocto Project docs was migrated from Docbook to Sphinx in YP
3.2. This 3.1 is an LTS release, and since 3.1 docs are 'close to'
the docs in 3.2, we agreed to backport sphinx docs onto 3.1.
This first patch brings all changes done in 3.2 until:
7f64574f7 README: include detailed information about sphinx
There are other changes after this commit, but they will be
selectively backported in individual patches.
This patch was generated with the following command:
git cherry-pick -n \
$(git log --reverse --oneline \
ac352ad7f95db7eeacb53c2778caa31800bd7c26..7f64574f7 \
| cut -f1 -d' ')
The following commits were applies in the dunfell docs, but not in
master, so they were first reverted (and squashed into this change). A
commit will reintroduce the content from these patches in the Sphinx
files in a followup patch.
069c27574 Documenation: Prepared for the 3.1.1 release
bd140f0f9 Documentation: Add 3.1.1 version updates missing from previous commit
17cc71a8f Documenation: Prepared for the 3.1.2 release
1a69e2c02 Documenation: Prepared for the 3.1.3 release
8910ac1c7 Documenation: Prepared for the 3.1.4 release
(From yocto-docs rev: c25fe058b88b893b0d146f3ed27320b47cdec236)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/README')
-rw-r--r-- | documentation/README | 283 |
1 files changed, 255 insertions, 28 deletions
diff --git a/documentation/README b/documentation/README index d64f2fd2f9..fce3cfe17e 100644 --- a/documentation/README +++ b/documentation/README | |||
@@ -40,16 +40,11 @@ Folders exist for individual manuals as follows: | |||
40 | * kernel-dev - The Yocto Project Linux Kernel Development Tasks Manual | 40 | * kernel-dev - The Yocto Project Linux Kernel Development Tasks Manual |
41 | * ref-manual - The Yocto Project Reference Manual | 41 | * ref-manual - The Yocto Project Reference Manual |
42 | * yocto-project-qs - The Yocto Project Quick Start | 42 | * yocto-project-qs - The Yocto Project Quick Start |
43 | * mega-manual - The Yocto Project Mega-Manual, which is an aggregated manual comprised | ||
44 | of all YP manuals and guides | ||
45 | * profile-manual - The Yocto Project Profile and Tracing Manual | 43 | * profile-manual - The Yocto Project Profile and Tracing Manual |
46 | * toaster-manual - The Toaster Manual | 44 | * toaster-manual - The Toaster Manual |
45 | * test-manual - The Test Environment Manual | ||
47 | 46 | ||
48 | Each folder is self-contained regarding content and figures. Note that there | 47 | Each folder is self-contained regarding content and figures. |
49 | is a sed file needed to process the links of the mega-manual. The sed file | ||
50 | is located in the tools directory. Also note that the figures folder in the | ||
51 | mega-manual directory contains duplicates of all the figures in the YP folders | ||
52 | directories for all YP manuals and guides. | ||
53 | 48 | ||
54 | If you want to find HTML versions of the Yocto Project manuals on the web, | 49 | If you want to find HTML versions of the Yocto Project manuals on the web, |
55 | go to http://www.yoctoproject.org and click on the "Documentation" tab. From | 50 | go to http://www.yoctoproject.org and click on the "Documentation" tab. From |
@@ -60,34 +55,266 @@ currently being developed. | |||
60 | In general, the Yocto Project site (http://www.yoctoproject.org) is a great | 55 | In general, the Yocto Project site (http://www.yoctoproject.org) is a great |
61 | reference for both information and downloads. | 56 | reference for both information and downloads. |
62 | 57 | ||
63 | Makefile | 58 | poky.yaml |
59 | ========= | ||
60 | |||
61 | This file defines variables used for documentation production. The variables | ||
62 | are used to define release pathnames, URLs for the published manuals, etc. | ||
63 | |||
64 | template | ||
64 | ======== | 65 | ======== |
66 | Contains various templates, fonts, and some old PNG files. | ||
67 | |||
68 | Sphinx | ||
69 | ====== | ||
70 | |||
71 | The Yocto Project documentation was migrated from the original DocBook | ||
72 | format to Sphinx based documentation for the Yocto Project 3.2 | ||
73 | release. This section will provide additional information related to | ||
74 | the Sphinx migration, and guidelines for developers willing to | ||
75 | contribute to the Yocto Project documentation. | ||
76 | |||
77 | Sphinx is a tool that makes it easy to create intelligent and | ||
78 | beautiful documentation, written by Georg Brandl and licensed under | ||
79 | the BSD license. It was originally created for the Python | ||
80 | documentation. | ||
81 | |||
82 | Extensive documentation is available on the Sphinx website: | ||
83 | https://www.sphinx-doc.org/en/master/. Sphinx is designed to be | ||
84 | extensible thanks to the ability to write our own custom extensions, | ||
85 | as Python modules, which will be executed during the generation of the | ||
86 | documentation. | ||
87 | |||
88 | Yocto Project documentation website | ||
89 | =================================== | ||
90 | |||
91 | A new website has been created to host the Yocto Project | ||
92 | documentation, it can be found at: https://docs.yoctoproject.org/. | ||
93 | |||
94 | The entire Yocto Project documentation, as well as the BitBake manual | ||
95 | is published on this website, including all previously released | ||
96 | versions. A version switcher was added, as a drop-down menu on the top | ||
97 | of the page to switch back and forth between the various versions of | ||
98 | the current active Yocto Project releases. | ||
99 | |||
100 | Transition pages have been added (as rst file) to show links to old | ||
101 | versions of the Yocto Project documentation with links to each manual | ||
102 | generated with DocBook. | ||
103 | |||
104 | How to build the Yocto Project documentation | ||
105 | ============================================ | ||
106 | |||
107 | Sphinx is written in Python. While it might work with Python2, for | ||
108 | obvious reasons, we will only support building the Yocto Project | ||
109 | documentation with Python3. | ||
110 | |||
111 | Sphinx might be available in your Linux distro packages repositories, | ||
112 | however it is not recommend using distro packages, as they might be | ||
113 | old versions, especially if you are using an LTS version of your | ||
114 | distro. The recommended method to install Sphinx and all required | ||
115 | dependencies is to use the Python Package Index (pip). | ||
116 | |||
117 | To install all required packages run: | ||
65 | 118 | ||
66 | The Makefile processes manual directories to create HTML, PDF, | 119 | $ pip3 install sphinx sphinx_rtd_theme pyyaml |
67 | tarballs, etc. Details on how the Makefile work are documented | ||
68 | inside the Makefile. See that file for more information. | ||
69 | 120 | ||
70 | To build a manual, you run the make command and pass it the name | 121 | To build the documentation locally, run: |
71 | of the folder containing the manual's contents. | ||
72 | For example, the following command run from the documentation directory | ||
73 | creates an HTML version of the SDK manual. | ||
74 | The DOC variable specifies the manual you are making: | ||
75 | 122 | ||
76 | $ make DOC=sdk-manual | 123 | $ cd documentation |
124 | $ make -f Makefile.sphinx html | ||
77 | 125 | ||
78 | poky.ent | 126 | The resulting HTML index page will be _build/html/index.html, and you |
127 | can browse your own copy of the locally generated documentation with | ||
128 | your browser. | ||
129 | |||
130 | Sphinx theme and CSS customization | ||
131 | ================================== | ||
132 | |||
133 | The Yocto Project documentation is currently based on the "Read the | ||
134 | Docs" Sphinx theme, with a few changes to make sure the look and feel | ||
135 | of the project documentation is preserved. | ||
136 | |||
137 | Most of the theme changes can be done using the file | ||
138 | 'sphinx-static/theme_overrides.css'. Most CSS changes in this file | ||
139 | were inherited from the DocBook CSS stylesheets. | ||
140 | |||
141 | Sphinx design guidelines and principles | ||
142 | ======================================= | ||
143 | |||
144 | The initial Docbook to Sphinx migration was done with an automated | ||
145 | tool called Pandoc (https://pandoc.org/). The tool produced some clean | ||
146 | output markdown text files. After the initial automated conversion | ||
147 | additional changes were done to fix up headings, images and links. In | ||
148 | addition Sphinx has built in mechanisms (directives) which were used | ||
149 | to replace similar functions implemented in Docbook such as glossary, | ||
150 | variables substitutions, notes and references. | ||
151 | |||
152 | Headings | ||
79 | ======== | 153 | ======== |
80 | 154 | ||
81 | This file defines variables used for documentation production. The variables | 155 | The layout of the Yocto Project manuals is organized as follows |
82 | are used to define release pathnames, URLs for the published manuals, etc. | ||
83 | 156 | ||
84 | template | 157 | Book |
158 | Chapter | ||
159 | Section | ||
160 | Section | ||
161 | Section | ||
162 | |||
163 | The following headings styles are defined in Sphinx: | ||
164 | |||
165 | Book => overline === | ||
166 | Chapter => overline *** | ||
167 | Section => ==== | ||
168 | Section => ---- | ||
169 | Section => ^^^^ | ||
170 | Section => """" or ~~~~ | ||
171 | |||
172 | With this proposal, we preserve the same TOCs between Sphinx and Docbook. | ||
173 | |||
174 | Built-in glossary | ||
175 | ================= | ||
176 | |||
177 | Sphinx has a glossary directive. From | ||
178 | https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary: | ||
179 | |||
180 | This directive must contain a reST definition list with terms and | ||
181 | definitions. The definitions will then be referencable with the | ||
182 | [https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-term | ||
183 | 'term' role]. | ||
184 | |||
185 | So anywhere in any of the Yocto Project manuals, :term:`VAR` can be | ||
186 | used to refer to an item from the glossary, and a link is created | ||
187 | automatically. A general index of terms is also generated by Sphinx | ||
188 | automatically. | ||
189 | |||
190 | Global substitutions | ||
191 | ==================== | ||
192 | |||
193 | The Yocto Project documentation makes heavy use of global | ||
194 | variables. In Docbook these variables are stored in the file | ||
195 | poky.ent. This Docbook feature is not handled automatically with | ||
196 | Pandoc. Sphinx has builtin support for substitutions | ||
197 | (https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions), | ||
198 | however there are important shortcomings. For example they cannot be | ||
199 | used/nested inside code-block sections. | ||
200 | |||
201 | A Sphinx extension was implemented to support variable substitutions | ||
202 | to mimic the DocBook based documentation behavior. Variabes | ||
203 | substitutions are done while reading/parsing the .rst files. The | ||
204 | pattern for variables substitutions is the same as with DocBook, | ||
205 | e.g. `&VAR;`. | ||
206 | |||
207 | The implementation of the extension can be found here in the file | ||
208 | documentation/sphinx/yocto-vars.py, this extension is enabled by | ||
209 | default when building the Yocto Project documentation. All variables | ||
210 | are set in a file call poky.yaml, which was initially generated from | ||
211 | poky.ent. The file was converted into YAML so that it is easier to | ||
212 | process by the custom Sphinx extension (which is a Python module). | ||
213 | |||
214 | For example, the following .rst content will produce the 'expected' | ||
215 | content: | ||
216 | |||
217 | .. code-block:: | ||
218 | $ mkdir ~/poky-&DISTRO; | ||
219 | or | ||
220 | $ git clone &YOCTO_GIT_URL;/git/poky -b &DISTRO_NAME_NO_CAP; | ||
221 | |||
222 | Variables can be nested, like it was the case for DocBook: | ||
223 | |||
224 | YOCTO_HOME_URL : "http://www.yoctoproject.org" | ||
225 | YOCTO_DOCS_URL : "&YOCTO_HOME_URL;/docs" | ||
226 | |||
227 | Note directive | ||
228 | ============== | ||
229 | |||
230 | Sphinx has a builtin 'note' directive that produces clean Note section | ||
231 | in the output file. There are various types of directives such as | ||
232 | "attention", "caution", "danger", "error", "hint", "important", "tip", | ||
233 | "warning", "admonition" that are supported, and additional directive | ||
234 | can be added as Sphinx extension if needed. | ||
235 | |||
236 | Figures | ||
237 | ======= | ||
238 | |||
239 | The Yocto Project documentation has many figures/images. Sphinx has a | ||
240 | 'figure' directive which is straight forward to use. To include a | ||
241 | figure in the body of the documentation: | ||
242 | |||
243 | .. image:: figures/YP-flow-diagram.png | ||
244 | |||
245 | Links and References | ||
246 | ==================== | ||
247 | |||
248 | The following types of links can be used: links to other locations in | ||
249 | the same document, to locations in other documents and to external | ||
250 | websites. | ||
251 | |||
252 | More information can be found here: | ||
253 | https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html. | ||
254 | |||
255 | References | ||
256 | ========== | ||
257 | |||
258 | The following extension is enabed by default: | ||
259 | sphinx.ext.autosectionlabel | ||
260 | (https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html). | ||
261 | |||
262 | This extension allows you to refer sections by their titles. Note that | ||
263 | autosectionlabel_prefix_document is enabled by default, so that we can | ||
264 | insert references from any document. | ||
265 | |||
266 | For example, to insert an HTML link to a section from | ||
267 | documentaion/manual/intro.rst, use: | ||
268 | |||
269 | Please check this :ref:`manual/intro:Cross-References to Locations in the Same Document` | ||
270 | |||
271 | Alternatively a custom text can be used instead of using the section | ||
272 | text: | ||
273 | |||
274 | Please check this :ref:`section <manual/intro:Cross-References to Locations in the Same Document>` | ||
275 | |||
276 | TIP: The following command can be used to dump all the references that | ||
277 | are defined in the project documentation: | ||
278 | |||
279 | python -msphinx.ext.intersphinx <path to build folder>/html/objects.inv | ||
280 | |||
281 | This dump contains all links and for each link it shows the default | ||
282 | "Link Text" that Sphinx would use. If the default link text is not | ||
283 | appropriate, a custom link text can be used in the ':ref:' directive. | ||
284 | |||
285 | Extlinks | ||
85 | ======== | 286 | ======== |
86 | Contains various templates, fonts, and some old PNG files. | ||
87 | 287 | ||
88 | tools | 288 | The sphinx.ext.extlinks extension is enabled by default |
89 | ===== | 289 | (https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html#use-the-external-links-extension), |
90 | Contains a tool to convert the DocBook files to PDF format. This folder also | 290 | and it is configured with: |
91 | contains the mega-manual.sed file, which is used by Makefile to process | 291 | |
92 | cross-references from within the manual that normally go to an external | 292 | 'yocto_home': ('https://yoctoproject.org%s', None), |
93 | manual. | 293 | 'yocto_wiki': ('https://wiki.yoctoproject.org%s', None), |
294 | 'yocto_dl': ('https://downloads.yoctoproject.org%s', None), | ||
295 | 'yocto_lists': ('https://lists.yoctoproject.org%s', None), | ||
296 | 'yocto_bugs': ('https://bugzilla.yoctoproject.org%s', None), | ||
297 | 'yocto_ab': ('https://autobuilder.yoctoproject.org%s', None), | ||
298 | 'yocto_docs': ('https://docs.yoctoproject.org%s', None), | ||
299 | 'yocto_git': ('https://git.yoctoproject.org%s', None), | ||
300 | 'oe_home': ('https://www.openembedded.org%s', None), | ||
301 | 'oe_lists': ('https://lists.openembedded.org%s', None), | ||
302 | |||
303 | It creates convenient shortcuts which can be used throughout the | ||
304 | documentation rst files, as: | ||
305 | |||
306 | Please check this :yocto_wiki:`wiki page </Weekly_Status>` | ||
307 | |||
308 | Intersphinx links | ||
309 | ================= | ||
310 | |||
311 | The sphinx.ext.intersphinx extension is enabled by default | ||
312 | (https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html), | ||
313 | so that we can cross reference content from other Sphinx based | ||
314 | documentation projects, such as the BitBake manual. | ||
315 | |||
316 | References to the bitbake manual can be done like this: | ||
317 | |||
318 | See the ":ref:`-D <bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax>`" option | ||
319 | or | ||
320 | :term:`bitbake:BB_NUMBER_PARSE_THREADS` | ||