]>
Commit | Line | Data |
---|---|---|
1e59de90 TL |
1 | .. _documenting_ceph: |
2 | ||
7c673cae FG |
3 | ================== |
4 | Documenting Ceph | |
5 | ================== | |
6 | ||
20effc67 | 7 | You can help the Ceph project by contributing to the documentation. Even |
1e59de90 | 8 | small contributions help the Ceph project. |
20effc67 TL |
9 | |
10 | The easiest way to suggest a correction to the documentation is to send an | |
11 | email to `ceph-users@ceph.io`. Include the string "ATTN: DOCS" or | |
12 | "Attention: Docs" or "Attention: Documentation" in the subject line. In | |
13 | the body of the email, include the text to be corrected (so that I can find | |
14 | it in the repo) and include your correction. | |
15 | ||
16 | Another way to suggest a documentation correction is to make a pull request. | |
17 | The instructions for making a pull request against the Ceph documentation are | |
18 | in the section :ref:`making_contributions`. | |
19 | ||
20 | If this is your first time making an improvement to the documentation or | |
21 | if you have noticed a small mistake (such as a spelling error or a typo), | |
22 | it will be easier to send an email than to make a pull request. You will | |
23 | be credited for the improvement unless you instruct Ceph Upstream | |
24 | Documentation not to credit you. | |
25 | ||
26 | Location of the Documentation in the Repository | |
27 | =============================================== | |
28 | ||
29 | The Ceph documentation source is in the ``ceph/doc`` directory of the Ceph | |
30 | repository. Python Sphinx renders the source into HTML and manpages. | |
31 | ||
32 | Viewing Old Ceph Documentation | |
33 | ============================== | |
2a845540 TL |
34 | The https://docs.ceph.com link displays the latest release branch by default |
35 | (for example, if "Quincy" is the most recent release, then by default | |
36 | https://docs.ceph.com displays the documentation for Quincy), but you can view | |
37 | the documentation for older versions of Ceph (for example, ``pacific``) by | |
38 | replacing the version name in the url (for example, ``quincy`` in | |
39 | `https://docs.ceph.com/en/pacific <https://docs.ceph.com/en/quincy>`_) with the | |
40 | branch name you prefer (for example, ``pacific``, to create a URL that reads | |
41 | `https://docs.ceph.com/en/pacific/ <https://docs.ceph.com/en/pacific/>`_). | |
20effc67 TL |
42 | |
43 | .. _making_contributions: | |
7c673cae FG |
44 | |
45 | Making Contributions | |
46 | ==================== | |
47 | ||
20effc67 TL |
48 | Making a documentation contribution involves the same basic procedure as making |
49 | a code contribution, with one exception: you must build documentation source | |
1e59de90 TL |
50 | instead of compiling program source. This sequence (the sequence of building |
51 | the documentation source) includes the following steps: | |
7c673cae FG |
52 | |
53 | #. `Get the Source`_ | |
54 | #. `Select a Branch`_ | |
55 | #. `Make a Change`_ | |
56 | #. `Build the Source`_ | |
57 | #. `Commit the Change`_ | |
58 | #. `Push the Change`_ | |
59 | #. `Make a Pull Request`_ | |
11fdf7f2 | 60 | #. `Notify Us`_ |
7c673cae FG |
61 | |
62 | Get the Source | |
63 | -------------- | |
64 | ||
1e59de90 TL |
65 | The source of the Ceph documentation is a collection of ReStructured Text files |
66 | that are in the Ceph repository in the ``ceph/doc`` directory. For details | |
67 | on GitHub and Ceph, see :ref:`Get Involved`. | |
7c673cae | 68 | |
1e59de90 TL |
69 | Use the `Fork and Pull`_ approach to make documentation contributions. To do |
70 | this, you must: | |
7c673cae | 71 | |
1e59de90 | 72 | #. Install git locally. In Debian or Ubuntu, run the following command: |
f67539c2 TL |
73 | |
74 | .. prompt:: bash $ | |
7c673cae FG |
75 | |
76 | sudo apt-get install git | |
77 | ||
1e59de90 | 78 | In Fedora, run the following command: |
f67539c2 TL |
79 | |
80 | .. prompt:: bash $ | |
7c673cae FG |
81 | |
82 | sudo yum install git | |
83 | ||
1e59de90 | 84 | In CentOS/RHEL, run the following command: |
f67539c2 TL |
85 | |
86 | .. prompt:: bash $ | |
7c673cae FG |
87 | |
88 | sudo yum install git | |
89 | ||
1e59de90 TL |
90 | #. Make sure that your ``.gitconfig`` file has been configured to include your |
91 | name and email address: | |
f67539c2 TL |
92 | |
93 | .. code-block:: ini | |
7c673cae FG |
94 | |
95 | [user] | |
96 | email = {your-email-address} | |
97 | name = {your-name} | |
98 | ||
f67539c2 TL |
99 | For example: |
100 | ||
101 | .. prompt:: bash $ | |
7c673cae FG |
102 | |
103 | git config --global user.name "John Doe" | |
104 | git config --global user.email johndoe@example.com | |
105 | ||
106 | ||
107 | #. Create a `github`_ account (if you don't have one). | |
108 | ||
109 | #. Fork the Ceph project. See https://github.com/ceph/ceph. | |
110 | ||
1e59de90 TL |
111 | #. Clone your fork of the Ceph project to your local host. This creates what is |
112 | known as a "local working copy". | |
7c673cae | 113 | |
1e59de90 | 114 | The Ceph documentation is organized by component: |
7c673cae | 115 | |
1e59de90 TL |
116 | - **Ceph Storage Cluster:** The Ceph Storage Cluster documentation is |
117 | in the ``doc/rados`` directory. | |
7c673cae | 118 | |
1e59de90 | 119 | - **Ceph Block Device:** The Ceph Block Device documentation is in |
7c673cae FG |
120 | the ``doc/rbd`` directory. |
121 | ||
1e59de90 | 122 | - **Ceph Object Storage:** The Ceph Object Storage documentation is in |
7c673cae FG |
123 | the ``doc/radosgw`` directory. |
124 | ||
1e59de90 | 125 | - **Ceph File System:** The Ceph File System documentation is in the |
7c673cae FG |
126 | ``doc/cephfs`` directory. |
127 | ||
1e59de90 | 128 | - **Installation (Quick):** Quick start documentation is in the |
7c673cae FG |
129 | ``doc/start`` directory. |
130 | ||
1e59de90 TL |
131 | - **Installation (Manual):** Documentaton concerning the manual installation of |
132 | Ceph is in the ``doc/install`` directory. | |
7c673cae | 133 | |
1e59de90 | 134 | - **Manpage:** Manpage source is in the ``doc/man`` directory. |
7c673cae | 135 | |
1e59de90 | 136 | - **Developer:** Developer documentation is in the ``doc/dev`` |
7c673cae FG |
137 | directory. |
138 | ||
1e59de90 TL |
139 | - **Images:** Images including JPEG and PNG files are stored in the |
140 | ``doc/images`` directory. | |
7c673cae FG |
141 | |
142 | ||
143 | Select a Branch | |
144 | --------------- | |
145 | ||
146 | When you make small changes to the documentation, such as fixing typographical | |
2a845540 TL |
147 | errors or clarifying explanations, use the ``main`` branch (default). You |
148 | should also use the ``main`` branch when making contributions to features that | |
149 | are in the current release. ``main`` is the most commonly used branch. : | |
f67539c2 TL |
150 | |
151 | .. prompt:: bash $ | |
7c673cae | 152 | |
2a845540 | 153 | git checkout main |
7c673cae FG |
154 | |
155 | When you make changes to documentation that affect an upcoming release, use | |
f67539c2 TL |
156 | the ``next`` branch. ``next`` is the second most commonly used branch. : |
157 | ||
158 | .. prompt:: bash $ | |
7c673cae FG |
159 | |
160 | git checkout next | |
161 | ||
162 | When you are making substantial contributions such as new features that are not | |
163 | yet in the current release; if your contribution is related to an issue with a | |
164 | tracker ID; or, if you want to see your documentation rendered on the Ceph.com | |
2a845540 | 165 | website before it gets merged into the ``main`` branch, you should create a |
7c673cae FG |
166 | branch. To distinguish branches that include only documentation updates, we |
167 | prepend them with ``wip-doc`` by convention, following the form | |
168 | ``wip-doc-{your-branch-name}``. If the branch relates to an issue filed in | |
169 | http://tracker.ceph.com/issues, the branch name incorporates the issue number. | |
170 | For example, if a documentation branch is a fix for issue #4000, the branch name | |
171 | should be ``wip-doc-4000`` by convention and the relevant tracker URL will be | |
172 | http://tracker.ceph.com/issues/4000. | |
173 | ||
174 | .. note:: Please do not mingle documentation contributions and source code | |
9f95a23c TL |
175 | contributions in a single commit. When you keep documentation |
176 | commits separate from source code commits, it simplifies the review | |
177 | process. We highly recommend that any pull request that adds a feature or | |
39ae355f TL |
178 | a configuration option should also include a documentation commit that |
179 | describes the changes. | |
7c673cae FG |
180 | |
181 | Before you create your branch name, ensure that it doesn't already exist in the | |
f67539c2 TL |
182 | local or remote repository. : |
183 | ||
184 | .. prompt:: bash $ | |
7c673cae FG |
185 | |
186 | git branch -a | grep wip-doc-{your-branch-name} | |
187 | ||
f67539c2 TL |
188 | If it doesn't exist, create your branch: |
189 | ||
190 | .. prompt:: bash $ | |
7c673cae FG |
191 | |
192 | git checkout -b wip-doc-{your-branch-name} | |
193 | ||
194 | ||
195 | Make a Change | |
196 | ------------- | |
197 | ||
f67539c2 | 198 | Modifying a document involves opening a reStructuredText file, changing |
7c673cae FG |
199 | its contents, and saving the changes. See `Documentation Style Guide`_ for |
200 | details on syntax requirements. | |
201 | ||
f67539c2 TL |
202 | Adding a document involves creating a new reStructuredText file within the |
203 | ``doc`` directory tree with a ``*.rst`` | |
204 | extension. You must also include a reference to the document: a hyperlink | |
7c673cae FG |
205 | or a table of contents entry. The ``index.rst`` file of a top-level directory |
206 | usually contains a TOC, where you can add the new file name. All documents must | |
207 | have a title. See `Headings`_ for details. | |
208 | ||
209 | Your new document doesn't get tracked by ``git`` automatically. When you want | |
210 | to add the document to the repository, you must use ``git add | |
211 | {path-to-filename}``. For example, from the top level directory of the | |
212 | repository, adding an ``example.rst`` file to the ``rados`` subdirectory would | |
f67539c2 TL |
213 | look like this: |
214 | ||
215 | .. prompt:: bash $ | |
7c673cae FG |
216 | |
217 | git add doc/rados/example.rst | |
218 | ||
219 | Deleting a document involves removing it from the repository with ``git rm | |
f67539c2 TL |
220 | {path-to-filename}``. For example: |
221 | ||
222 | .. prompt:: bash $ | |
7c673cae FG |
223 | |
224 | git rm doc/rados/example.rst | |
225 | ||
226 | You must also remove any reference to a deleted document from other documents. | |
227 | ||
228 | ||
229 | Build the Source | |
230 | ---------------- | |
231 | ||
f67539c2 TL |
232 | To build the documentation, navigate to the ``ceph`` repository directory: |
233 | ||
234 | ||
235 | .. prompt:: bash $ | |
7c673cae FG |
236 | |
237 | cd ceph | |
238 | ||
f67539c2 TL |
239 | .. note:: |
240 | The directory that contains ``build-doc`` and ``serve-doc`` must be included | |
241 | in the ``PATH`` environment variable in order for these commands to work. | |
242 | ||
243 | ||
244 | To build the documentation on Debian/Ubuntu, Fedora, or CentOS/RHEL, execute: | |
245 | ||
246 | .. prompt:: bash $ | |
7c673cae FG |
247 | |
248 | admin/build-doc | |
249 | ||
f67539c2 TL |
250 | To scan for the reachability of external links, execute: |
251 | ||
252 | .. prompt:: bash $ | |
7c673cae FG |
253 | |
254 | admin/build-doc linkcheck | |
255 | ||
f67539c2 TL |
256 | Executing ``admin/build-doc`` will create a ``build-doc`` directory under |
257 | ``ceph``. You may need to create a directory under ``ceph/build-doc`` for | |
258 | output of Javadoc files: | |
259 | ||
260 | .. prompt:: bash $ | |
7c673cae FG |
261 | |
262 | mkdir -p output/html/api/libcephfs-java/javadoc | |
263 | ||
264 | The build script ``build-doc`` will produce an output of errors and warnings. | |
f67539c2 TL |
265 | You MUST fix errors in documents you modified before committing a change, and |
266 | you SHOULD fix warnings that are related to syntax you modified. | |
7c673cae FG |
267 | |
268 | .. important:: You must validate ALL HYPERLINKS. If a hyperlink is broken, | |
269 | it automatically breaks the build! | |
270 | ||
11fdf7f2 | 271 | Once you build the documentation set, you may start an HTTP server at |
f67539c2 TL |
272 | ``http://localhost:8080/`` to view it: |
273 | ||
274 | .. prompt:: bash $ | |
7c673cae | 275 | |
11fdf7f2 | 276 | admin/serve-doc |
7c673cae | 277 | |
11fdf7f2 | 278 | You can also navigate to ``build-doc/output`` to inspect the built documents. |
7c673cae FG |
279 | There should be an ``html`` directory and a ``man`` directory containing |
280 | documentation in HTML and manpage formats respectively. | |
281 | ||
282 | Build the Source (First Time) | |
283 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
284 | ||
285 | Ceph uses Python Sphinx, which is generally distribution agnostic. The first | |
286 | time you build Ceph documentation, it will generate a doxygen XML tree, which | |
287 | is a bit time consuming. | |
288 | ||
289 | Python Sphinx does have some dependencies that vary across distributions. The | |
290 | first time you build the documentation, the script will notify you if you do not | |
291 | have the dependencies installed. To run Sphinx and build documentation successfully, | |
292 | the following packages are required: | |
293 | ||
294 | .. raw:: html | |
295 | ||
296 | <style type="text/css">div.body h3{margin:5px 0px 0px 0px;}</style> | |
297 | <table cellpadding="10"><colgroup><col width="30%"><col width="30%"><col width="30%"></colgroup><tbody valign="top"><tr><td><h3>Debian/Ubuntu</h3> | |
298 | ||
299 | - gcc | |
a4b75251 TL |
300 | - python3-dev |
301 | - python3-pip | |
302 | - python3-sphinx | |
20effc67 | 303 | - python3-venv |
7c673cae FG |
304 | - libxml2-dev |
305 | - libxslt1-dev | |
306 | - doxygen | |
307 | - graphviz | |
308 | - ant | |
309 | - ditaa | |
310 | ||
311 | .. raw:: html | |
312 | ||
313 | </td><td><h3>Fedora</h3> | |
314 | ||
315 | - gcc | |
316 | - python-devel | |
317 | - python-pip | |
7c673cae FG |
318 | - python-docutils |
319 | - python-jinja2 | |
320 | - python-pygments | |
321 | - python-sphinx | |
322 | - libxml2-devel | |
323 | - libxslt1-devel | |
324 | - doxygen | |
325 | - graphviz | |
326 | - ant | |
327 | - ditaa | |
328 | ||
329 | .. raw:: html | |
330 | ||
331 | </td><td><h3>CentOS/RHEL</h3> | |
332 | ||
333 | - gcc | |
334 | - python-devel | |
335 | - python-pip | |
7c673cae FG |
336 | - python-docutils |
337 | - python-jinja2 | |
338 | - python-pygments | |
339 | - python-sphinx | |
340 | - libxml2-dev | |
341 | - libxslt1-dev | |
342 | - doxygen | |
343 | - graphviz | |
344 | - ant | |
345 | ||
346 | .. raw:: html | |
347 | ||
348 | </td></tr></tbody></table> | |
349 | ||
350 | ||
c07f9fc5 | 351 | Install each dependency that is not installed on your host. For Debian/Ubuntu |
f67539c2 TL |
352 | distributions, execute the following: |
353 | ||
354 | .. prompt:: bash $ | |
7c673cae | 355 | |
1e59de90 TL |
356 | sudo apt-get install gcc python-dev python3-pip libxml2-dev libxslt-dev doxygen graphviz ant ditaa |
357 | sudo apt-get install python3-sphinx python3-venv | |
7c673cae | 358 | |
f67539c2 TL |
359 | For Fedora distributions, execute the following: |
360 | ||
361 | .. prompt:: bash $ | |
7c673cae | 362 | |
a4b75251 | 363 | sudo yum install gcc python-devel python-pip libxml2-devel libxslt-devel doxygen graphviz ant |
7c673cae FG |
364 | sudo pip install html2text |
365 | sudo yum install python-jinja2 python-pygments python-docutils python-sphinx | |
366 | sudo yum install jericho-html ditaa | |
367 | ||
368 | For CentOS/RHEL distributions, it is recommended to have ``epel`` (Extra | |
369 | Packages for Enterprise Linux) repository as it provides some extra packages | |
370 | which are not available in the default repository. To install ``epel``, execute | |
f67539c2 TL |
371 | the following: |
372 | ||
373 | .. prompt:: bash $ | |
7c673cae FG |
374 | |
375 | sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm | |
376 | ||
f67539c2 TL |
377 | For CentOS/RHEL distributions, execute the following: |
378 | ||
379 | .. prompt:: bash $ | |
7c673cae | 380 | |
a4b75251 | 381 | sudo yum install gcc python-devel python-pip libxml2-devel libxslt-devel doxygen graphviz ant |
7c673cae FG |
382 | sudo pip install html2text |
383 | ||
f67539c2 TL |
384 | For CentOS/RHEL distributions, the remaining python packages are not available |
385 | in the default and ``epel`` repositories. So, use http://rpmfind.net/ to find | |
386 | the packages. Then, download them from a mirror and install them. For example: | |
387 | ||
388 | .. prompt:: bash $ | |
7c673cae FG |
389 | |
390 | wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-jinja2-2.7.2-2.el7.noarch.rpm | |
391 | sudo yum install python-jinja2-2.7.2-2.el7.noarch.rpm | |
392 | wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-pygments-1.4-9.el7.noarch.rpm | |
393 | sudo yum install python-pygments-1.4-9.el7.noarch.rpm | |
394 | wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-docutils-0.11-0.2.20130715svn7687.el7.noarch.rpm | |
395 | sudo yum install python-docutils-0.11-0.2.20130715svn7687.el7.noarch.rpm | |
396 | wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-sphinx-1.1.3-11.el7.noarch.rpm | |
397 | sudo yum install python-sphinx-1.1.3-11.el7.noarch.rpm | |
398 | ||
c07f9fc5 | 399 | Ceph documentation makes extensive use of `ditaa`_, which is not presently built |
7c673cae FG |
400 | for CentOS/RHEL7. You must install ``ditaa`` if you are making changes to |
401 | ``ditaa`` diagrams so that you can verify that they render properly before you | |
402 | commit new or modified ``ditaa`` diagrams. You may retrieve compatible required | |
f67539c2 TL |
403 | packages for CentOS/RHEL distributions and install them manually. To run |
404 | ``ditaa`` on CentOS/RHEL7, following dependencies are required: | |
7c673cae FG |
405 | |
406 | - jericho-html | |
407 | - jai-imageio-core | |
408 | - batik | |
409 | ||
410 | Use http://rpmfind.net/ to find compatible ``ditaa`` and the dependencies. | |
f67539c2 TL |
411 | Then, download them from a mirror and install them. For example: |
412 | ||
413 | .. prompt:: bash $ | |
7c673cae FG |
414 | |
415 | wget http://rpmfind.net/linux/fedora/linux/releases/22/Everything/x86_64/os/Packages/j/jericho-html-3.3-4.fc22.noarch.rpm | |
416 | sudo yum install jericho-html-3.3-4.fc22.noarch.rpm | |
417 | wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/jai-imageio-core-1.2-0.14.20100217cvs.el7.noarch.rpm | |
418 | sudo yum install jai-imageio-core-1.2-0.14.20100217cvs.el7.noarch.rpm | |
419 | wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/batik-1.8-0.12.svn1230816.el7.noarch.rpm | |
420 | sudo yum install batik-1.8-0.12.svn1230816.el7.noarch.rpm | |
421 | wget http://rpmfind.net/linux/fedora/linux/releases/22/Everything/x86_64/os/Packages/d/ditaa-0.9-13.r74.fc21.noarch.rpm | |
422 | sudo yum install ditaa-0.9-13.r74.fc21.noarch.rpm | |
423 | ||
424 | Once you have installed all these packages, build the documentation by following | |
31f18b77 FG |
425 | the steps given in `Build the Source`_. |
426 | ||
7c673cae FG |
427 | |
428 | Commit the Change | |
429 | ----------------- | |
430 | ||
431 | Ceph documentation commits are simple, but follow a strict convention: | |
432 | ||
433 | - A commit SHOULD have 1 file per commit (it simplifies rollback). You MAY | |
434 | commit multiple files with related changes. Unrelated changes SHOULD NOT | |
435 | be put into the same commit. | |
436 | - A commit MUST have a comment. | |
437 | - A commit comment MUST be prepended with ``doc:``. (strict) | |
438 | - The comment summary MUST be one line only. (strict) | |
439 | - Additional comments MAY follow a blank line after the summary, | |
440 | but should be terse. | |
20effc67 | 441 | - A commit MAY include ``Fixes: https://tracker.ceph.com/issues/{bug number}``. |
7c673cae FG |
442 | - Commits MUST include ``Signed-off-by: Firstname Lastname <email>``. (strict) |
443 | ||
444 | .. tip:: Follow the foregoing convention particularly where it says | |
445 | ``(strict)`` or you will be asked to modify your commit to comply with | |
446 | this convention. | |
447 | ||
448 | The following is a common commit comment (preferred):: | |
449 | ||
450 | doc: Fixes a spelling error and a broken hyperlink. | |
451 | ||
452 | Signed-off-by: John Doe <john.doe@gmail.com> | |
453 | ||
454 | ||
455 | The following comment includes a reference to a bug. :: | |
456 | ||
457 | doc: Fixes a spelling error and a broken hyperlink. | |
458 | ||
20effc67 | 459 | Fixes: https://tracker.ceph.com/issues/1234 |
7c673cae FG |
460 | |
461 | Signed-off-by: John Doe <john.doe@gmail.com> | |
462 | ||
463 | ||
464 | The following comment includes a terse sentence following the comment summary. | |
465 | There is a carriage return between the summary line and the description:: | |
466 | ||
467 | doc: Added mon setting to monitor config reference | |
468 | ||
469 | Describes 'mon setting', which is a new setting added | |
470 | to config_opts.h. | |
471 | ||
472 | Signed-off-by: John Doe <john.doe@gmail.com> | |
473 | ||
474 | ||
f67539c2 TL |
475 | To commit changes, execute the following: |
476 | ||
477 | .. prompt:: bash $ | |
7c673cae FG |
478 | |
479 | git commit -a | |
480 | ||
481 | ||
482 | An easy way to manage your documentation commits is to use visual tools for | |
483 | ``git``. For example, ``gitk`` provides a graphical interface for viewing the | |
484 | repository history, and ``git-gui`` provides a graphical interface for viewing | |
485 | your uncommitted changes, staging them for commit, committing the changes and | |
486 | pushing them to your forked Ceph repository. | |
487 | ||
488 | ||
f67539c2 TL |
489 | For Debian/Ubuntu, execute: |
490 | ||
491 | .. prompt:: bash $ | |
7c673cae FG |
492 | |
493 | sudo apt-get install gitk git-gui | |
494 | ||
f67539c2 TL |
495 | For Fedora/CentOS/RHEL, execute: |
496 | ||
497 | .. prompt:: bash $ | |
7c673cae FG |
498 | |
499 | sudo yum install gitk git-gui | |
500 | ||
f67539c2 TL |
501 | Then, execute: |
502 | ||
503 | .. prompt:: bash $ | |
7c673cae FG |
504 | |
505 | cd {git-ceph-repo-path} | |
506 | gitk | |
507 | ||
508 | Finally, select **File->Start git gui** to activate the graphical user interface. | |
509 | ||
510 | ||
511 | Push the Change | |
512 | --------------- | |
513 | ||
514 | Once you have one or more commits, you must push them from the local copy of the | |
515 | repository to ``github``. A graphical tool like ``git-gui`` provides a user | |
f67539c2 TL |
516 | interface for pushing to the repository. If you created a branch previously: |
517 | ||
518 | .. prompt:: bash $ | |
7c673cae FG |
519 | |
520 | git push origin wip-doc-{your-branch-name} | |
521 | ||
f67539c2 TL |
522 | Otherwise: |
523 | ||
524 | .. prompt:: bash $ | |
7c673cae FG |
525 | |
526 | git push | |
527 | ||
528 | ||
529 | Make a Pull Request | |
530 | ------------------- | |
531 | ||
532 | As noted earlier, you can make documentation contributions using the `Fork and | |
533 | Pull`_ approach. | |
534 | ||
535 | ||
1e59de90 TL |
536 | Squash Extraneous Commits |
537 | ------------------------- | |
538 | Each pull request ought to be associated with only a single commit. If you have | |
539 | made more than one commit to the feature branch that you are working in, you | |
540 | will need to "squash" the multiple commits. "Squashing" is the colloquial term | |
541 | for a particular kind of "interactive rebase". Squashing can be done in a great | |
542 | number of ways, but the example here will deal with a situation in which there | |
543 | are three commits and the changes in all three of the commits are kept. The three | |
544 | commits will be squashed into a single commit. | |
545 | ||
546 | #. Make the commits that you will later squash. | |
547 | ||
548 | #. Make the first commit. | |
549 | ||
550 | :: | |
551 | ||
552 | doc/glossary: improve "CephX" entry | |
553 | ||
554 | Improve the glossary entry for "CephX". | |
555 | ||
556 | Signed-off-by: Zac Dover <zac.dover@proton.me> | |
557 | ||
558 | # Please enter the commit message for your changes. Lines starting | |
559 | # with '#' will be ignored, and an empty message aborts the commit. | |
560 | # | |
561 | # On branch wip-doc-2023-03-28-glossary-cephx | |
562 | # Changes to be committed: | |
563 | # modified: glossary.rst | |
564 | # | |
565 | ||
566 | #. Make the second commit. | |
567 | ||
568 | :: | |
569 | ||
570 | doc/glossary: add link to architecture doc | |
571 | ||
572 | Add a link to a section in the architecture document, which link | |
573 | will be used in the process of improving the "CephX" glossary entry. | |
574 | ||
575 | Signed-off-by: Zac Dover <zac.dover@proton.me> | |
576 | ||
577 | # Please enter the commit message for your changes. Lines starting | |
578 | # with '#' will be ignored, and an empty message aborts the commit. | |
579 | # | |
580 | # On branch wip-doc-2023-03-28-glossary-cephx | |
581 | # Your branch is up to date with 'origin/wip-doc-2023-03-28-glossary-cephx'. | |
582 | # | |
583 | # Changes to be committed: | |
584 | # modified: architecture.rst | |
585 | ||
586 | #. Make the third commit. | |
587 | ||
588 | :: | |
589 | ||
590 | doc/glossary: link to Arch doc in "CephX" glossary | |
591 | ||
592 | Link to the Architecture document from the "CephX" entry in the | |
593 | Glossary. | |
594 | ||
595 | Signed-off-by: Zac Dover <zac.dover@proton.me> | |
596 | ||
597 | # Please enter the commit message for your changes. Lines starting | |
598 | # with '#' will be ignored, and an empty message aborts the commit. | |
599 | # | |
600 | # On branch wip-doc-2023-03-28-glossary-cephx | |
601 | # Your branch is up to date with 'origin/wip-doc-2023-03-28-glossary-cephx'. | |
602 | # | |
603 | # Changes to be committed: | |
604 | # modified: glossary.rst | |
605 | ||
606 | #. There are now three commits in the feature branch. We will now begin the | |
607 | process of squashing them into a single commit. | |
608 | ||
609 | #. Run the command ``git rebase -i main``, which rebases the current branch | |
610 | (the feature branch) against the ``main`` branch: | |
611 | ||
612 | .. prompt:: bash | |
613 | ||
614 | git rebase -i main | |
615 | ||
616 | #. A list of the commits that have been made to the feature branch now | |
617 | appear, and looks like this: | |
618 | ||
619 | :: | |
620 | ||
621 | pick d395e500883 doc/glossary: improve "CephX" entry | |
622 | pick b34986e2922 doc/glossary: add link to architecture doc | |
623 | pick 74d0719735c doc/glossary: link to Arch doc in "CephX" glossary | |
624 | ||
625 | # Rebase 0793495b9d1..74d0719735c onto 0793495b9d1 (3 commands) | |
626 | # | |
627 | # Commands: | |
628 | # p, pick <commit> = use commit | |
629 | # r, reword <commit> = use commit, but edit the commit message | |
630 | # e, edit <commit> = use commit, but stop for amending | |
631 | # s, squash <commit> = use commit, but meld into previous commit | |
632 | # f, fixup [-C | -c] <commit> = like "squash" but keep only the previous | |
633 | # commit's log message, unless -C is used, in which case | |
634 | # keep only this commit's message; -c is same as -C but | |
635 | # opens the editor | |
636 | # x, exec <command> = run command (the rest of the line) using shell | |
637 | # b, break = stop here (continue rebase later with 'git rebase --continue') | |
638 | # d, drop <commit> = remove commit | |
639 | # l, label <label> = label current HEAD with a name | |
640 | # t, reset <label> = reset HEAD to a label | |
641 | # m, merge [-C <commit> | -c <commit>] <label> [# <oneline>] | |
642 | # create a merge commit using the original merge commit's | |
643 | # message (or the oneline, if no original merge commit was | |
644 | # specified); use -c <commit> to reword the commit message | |
645 | # u, update-ref <ref> = track a placeholder for the <ref> to be updated | |
646 | # to this position in the new commits. The <ref> is | |
647 | # updated at the end of the rebase | |
648 | # | |
649 | # These lines can be re-ordered; they are executed from top to bottom. | |
650 | # | |
651 | # If you remove a line here THAT COMMIT WILL BE LOST. | |
652 | ||
653 | Find the part of the screen that says "pick". This is the part that you will | |
654 | alter. There are three commits that are currently labeled "pick". We will | |
655 | choose one of them to remain labeled "pick", and we will label the other two | |
656 | commits "squash". | |
657 | ||
658 | #. Label two of the three commits ``squash``: | |
659 | ||
660 | :: | |
661 | ||
662 | pick d395e500883 doc/glossary: improve "CephX" entry | |
663 | squash b34986e2922 doc/glossary: add link to architecture doc | |
664 | squash 74d0719735c doc/glossary: link to Arch doc in "CephX" glossary | |
665 | ||
666 | # Rebase 0793495b9d1..74d0719735c onto 0793495b9d1 (3 commands) | |
667 | # | |
668 | # Commands: | |
669 | # p, pick <commit> = use commit | |
670 | # r, reword <commit> = use commit, but edit the commit message | |
671 | # e, edit <commit> = use commit, but stop for amending | |
672 | # s, squash <commit> = use commit, but meld into previous commit | |
673 | # f, fixup [-C | -c] <commit> = like "squash" but keep only the previous | |
674 | # commit's log message, unless -C is used, in which case | |
675 | # keep only this commit's message; -c is same as -C but | |
676 | # opens the editor | |
677 | # x, exec <command> = run command (the rest of the line) using shell | |
678 | # b, break = stop here (continue rebase later with 'git rebase --continue') | |
679 | # d, drop <commit> = remove commit | |
680 | # l, label <label> = label current HEAD with a name | |
681 | # t, reset <label> = reset HEAD to a label | |
682 | # m, merge [-C <commit> | -c <commit>] <label> [# <oneline>] | |
683 | # create a merge commit using the original merge commit's | |
684 | # message (or the oneline, if no original merge commit was | |
685 | # specified); use -c <commit> to reword the commit message | |
686 | # u, update-ref <ref> = track a placeholder for the <ref> to be updated | |
687 | # to this position in the new commits. The <ref> is | |
688 | # updated at the end of the rebase | |
689 | # | |
690 | # These lines can be re-ordered; they are executed from top to bottom. | |
691 | # | |
692 | # If you remove a line here THAT COMMIT WILL BE LOST. | |
693 | ||
694 | #. Now we create a commit message that applies to all the commits that have | |
695 | been squashed together: | |
696 | ||
697 | #. When you save and close the list of commits that you have designated for | |
698 | squashing, a list of all three commit messages appears, and it looks | |
699 | like this: | |
700 | ||
701 | :: | |
702 | ||
703 | # This is a combination of 3 commits. | |
704 | # This is the 1st commit message: | |
705 | ||
706 | doc/glossary: improve "CephX" entry | |
707 | ||
708 | Improve the glossary entry for "CephX". | |
709 | ||
710 | Signed-off-by: Zac Dover <zac.dover@proton.me> | |
711 | ||
712 | # This is the commit message #2: | |
713 | ||
714 | doc/glossary: add link to architecture doc | |
715 | ||
716 | Add a link to a section in the architecture document, which link | |
717 | will be used in the process of improving the "CephX" glossary entry. | |
718 | ||
719 | Signed-off-by: Zac Dover <zac.dover@proton.me> | |
720 | ||
721 | # This is the commit message #3: | |
722 | ||
723 | doc/glossary: link to Arch doc in "CephX" glossary | |
724 | ||
725 | Link to the Architecture document from the "CephX" entry in the | |
726 | Glossary. | |
727 | ||
728 | Signed-off-by: Zac Dover <zac.dover@proton.me> | |
729 | ||
730 | # Please enter the commit message for your changes. Lines starting | |
731 | # with '#' will be ignored, and an empty message aborts the commit. | |
732 | # | |
733 | # Date: Tue Mar 28 18:42:11 2023 +1000 | |
734 | # | |
735 | # interactive rebase in progress; onto 0793495b9d1 | |
736 | # Last commands done (3 commands done): | |
737 | # squash b34986e2922 doc/glossary: add link to architecture doc | |
738 | # squash 74d0719735c doc/glossary: link to Arch doc in "CephX" glossary | |
739 | # No commands remaining. | |
740 | # You are currently rebasing branch 'wip-doc-2023-03-28-glossary-cephx' on '0793495b9d1'. | |
741 | # | |
742 | # Changes to be committed: | |
743 | # modified: doc/architecture.rst | |
744 | # modified: doc/glossary.rst | |
745 | ||
746 | #. The commit messages have been revised into the simpler form presented here: | |
747 | ||
748 | :: | |
749 | ||
750 | doc/glossary: improve "CephX" entry | |
751 | ||
752 | Improve the glossary entry for "CephX". | |
753 | ||
754 | Signed-off-by: Zac Dover <zac.dover@proton.me> | |
755 | ||
756 | # Please enter the commit message for your changes. Lines starting | |
757 | # with '#' will be ignored, and an empty message aborts the commit. | |
758 | # | |
759 | # Date: Tue Mar 28 18:42:11 2023 +1000 | |
760 | # | |
761 | # interactive rebase in progress; onto 0793495b9d1 | |
762 | # Last commands done (3 commands done): | |
763 | # squash b34986e2922 doc/glossary: add link to architecture doc | |
764 | # squash 74d0719735c doc/glossary: link to Arch doc in "CephX" glossary | |
765 | # No commands remaining. | |
766 | # You are currently rebasing branch 'wip-doc-2023-03-28-glossary-cephx' on '0793495b9d1'. | |
767 | # | |
768 | # Changes to be committed: | |
769 | # modified: doc/architecture.rst | |
770 | # modified: doc/glossary.rst | |
771 | ||
772 | #. Force push the squashed commit from your local working copy to the remote | |
773 | upstream branch. The force push is necessary because the newly squashed commit | |
774 | does not have an ancestor in the remote. If that confuses you, just run this | |
775 | command and don't think too much about it: | |
776 | ||
777 | .. prompt:: bash $ | |
778 | ||
779 | git push -f | |
780 | ||
781 | :: | |
782 | ||
783 | Enumerating objects: 9, done. | |
784 | Counting objects: 100% (9/9), done. | |
785 | Delta compression using up to 8 threads | |
786 | Compressing objects: 100% (5/5), done. | |
787 | Writing objects: 100% (5/5), 722 bytes | 722.00 KiB/s, done. | |
788 | Total 5 (delta 4), reused 0 (delta 0), pack-reused 0 | |
789 | remote: Resolving deltas: 100% (4/4), completed with 4 local objects. | |
790 | To github.com:zdover23/ceph.git | |
791 | + b34986e2922...02e3a5cb763 wip-doc-2023-03-28-glossary-cephx -> wip-doc-2023-03-28-glossary-cephx (forced update) | |
792 | ||
793 | ||
794 | ||
795 | ||
7c673cae | 796 | |
11fdf7f2 TL |
797 | Notify Us |
798 | --------- | |
7c673cae | 799 | |
1e59de90 TL |
800 | If some time has passed and the pull request that you raised has not been |
801 | reviewed, contact the component lead and ask what's taking so long. See | |
802 | :ref:`ctl` for a list of component leads. | |
7c673cae FG |
803 | |
804 | Documentation Style Guide | |
805 | ========================= | |
806 | ||
807 | One objective of the Ceph documentation project is to ensure the readability of | |
20effc67 | 808 | the documentation in both native reStructuredText format and its rendered |
7c673cae FG |
809 | formats such as HTML. Navigate to your Ceph repository and view a document in |
810 | its native format. You may notice that it is generally as legible in a terminal | |
811 | as it is in its rendered HTML format. Additionally, you may also notice that | |
f67539c2 TL |
812 | diagrams in ``ditaa`` format also render reasonably well in text mode. : |
813 | ||
814 | .. prompt:: bash $ | |
7c673cae | 815 | |
11fdf7f2 | 816 | less doc/architecture.rst |
7c673cae FG |
817 | |
818 | Review the following style guides to maintain this consistency. | |
819 | ||
820 | ||
821 | Headings | |
822 | -------- | |
823 | ||
824 | #. **Document Titles:** Document titles use the ``=`` character overline and | |
825 | underline with a leading and trailing space on the title text line. | |
826 | See `Document Title`_ for details. | |
827 | ||
828 | #. **Section Titles:** Section tiles use the ``=`` character underline with no | |
829 | leading or trailing spaces for text. Two carriage returns should precede a | |
830 | section title (unless an inline reference precedes it). See `Sections`_ for | |
831 | details. | |
832 | ||
833 | #. **Subsection Titles:** Subsection titles use the ``_`` character underline | |
834 | with no leading or trailing spaces for text. Two carriage returns should | |
835 | precede a subsection title (unless an inline reference precedes it). | |
836 | ||
837 | ||
838 | Text Body | |
839 | --------- | |
840 | ||
841 | As a general rule, we prefer text to wrap at column 80 so that it is legible in | |
842 | a command line interface without leading or trailing white space. Where | |
843 | possible, we prefer to maintain this convention with text, lists, literal text | |
844 | (exceptions allowed), tables, and ``ditaa`` graphics. | |
845 | ||
846 | #. **Paragraphs**: Paragraphs have a leading and a trailing carriage return, | |
847 | and should be 80 characters wide or less so that the documentation can be | |
848 | read in native format in a command line terminal. | |
849 | ||
850 | #. **Literal Text:** To create an example of literal text (e.g., command line | |
851 | usage), terminate the preceding paragraph with ``::`` or enter a carriage | |
852 | return to create an empty line after the preceding paragraph; then, enter | |
853 | ``::`` on a separate line followed by another empty line. Then, begin the | |
854 | literal text with tab indentation (preferred) or space indentation of 3 | |
855 | characters. | |
856 | ||
857 | #. **Indented Text:** Indented text such as bullet points | |
858 | (e.g., ``- some text``) may span multiple lines. The text of subsequent | |
859 | lines should begin at the same character position as the text of the | |
860 | indented text (less numbers, bullets, etc.). | |
861 | ||
862 | Indented text may include literal text examples. Whereas, text indentation | |
863 | should be done with spaces, literal text examples should be indented with | |
864 | tabs. This convention enables you to add an additional indented paragraph | |
865 | following a literal example by leaving a blank line and beginning the | |
866 | subsequent paragraph with space indentation. | |
867 | ||
868 | #. **Numbered Lists:** Numbered lists should use autonumbering by starting | |
869 | a numbered indent with ``#.`` instead of the actual number so that | |
870 | numbered paragraphs can be repositioned without requiring manual | |
871 | renumbering. | |
872 | ||
873 | #. **Code Examples:** Ceph supports the use of the | |
874 | ``.. code-block::<language>`` role, so that you can add highlighting to | |
875 | source examples. This is preferred for source code. However, use of this | |
876 | tag will cause autonumbering to restart at 1 if it is used as an example | |
877 | within a numbered list. See `Showing code examples`_ for details. | |
878 | ||
879 | ||
880 | Paragraph Level Markup | |
881 | ---------------------- | |
882 | ||
883 | The Ceph project uses `paragraph level markup`_ to highlight points. | |
884 | ||
885 | #. **Tip:** Use the ``.. tip::`` directive to provide additional information | |
886 | that assists the reader or steers the reader away from trouble. | |
887 | ||
888 | #. **Note**: Use the ``.. note::`` directive to highlight an important point. | |
889 | ||
890 | #. **Important:** Use the ``.. important::`` directive to highlight important | |
891 | requirements or caveats (e.g., anything that could lead to data loss). Use | |
892 | this directive sparingly, because it renders in red. | |
893 | ||
894 | #. **Version Added:** Use the ``.. versionadded::`` directive for new features | |
895 | or configuration settings so that users know the minimum release for using | |
896 | a feature. | |
897 | ||
898 | #. **Version Changed:** Use the ``.. versionchanged::`` directive for changes | |
899 | in usage or configuration settings. | |
900 | ||
901 | #. **Deprecated:** Use the ``.. deprecated::`` directive when CLI usage, | |
902 | a feature or a configuration setting is no longer preferred or will be | |
903 | discontinued. | |
904 | ||
905 | #. **Topic:** Use the ``.. topic::`` directive to encapsulate text that is | |
906 | outside the main flow of the document. See the `topic directive`_ for | |
907 | additional details. | |
908 | ||
909 | ||
39ae355f TL |
910 | Table of Contents (TOC) and Hyperlinks |
911 | --------------------------------------- | |
7c673cae | 912 | |
39ae355f TL |
913 | The documents in the Ceph documentation suite follow certain conventions that |
914 | are explained in this section. | |
7c673cae | 915 | |
39ae355f TL |
916 | Every document (every ``.rst`` file) in the Sphinx-controlled Ceph |
917 | documentation suite must be linked either (1) from another document in the | |
918 | documentation suite or (2) from a table of contents (TOC). If any document in | |
919 | the documentation suite is not linked in this way, the ``build-doc`` script | |
920 | generates warnings when it tries to build the documentation. | |
7c673cae | 921 | |
39ae355f TL |
922 | The Ceph project uses the ``.. toctree::`` directive. See `The TOC tree`_ for |
923 | details. When rendering a table of contents (TOC), specify the ``:maxdepth:`` | |
924 | parameter so that the rendered TOC is not too long. | |
7c673cae | 925 | |
39ae355f TL |
926 | Use the ``:ref:`` syntax where a link target contains a specific unique |
927 | identifier (for example, ``.. _unique-target-id:``). A link to the section | |
928 | designated by ``.. _unique-target-id:`` looks like this: | |
929 | ``:ref:`unique-target-id```. If this convention is followed, the links within | |
930 | the ``.rst`` source files will work even if the source files are moved within | |
931 | the ``ceph/doc`` directory. See `Cross referencing arbitrary locations`_ for | |
932 | details. | |
7c673cae | 933 | |
39ae355f | 934 | .. _start_external_hyperlink_example: |
7c673cae | 935 | |
39ae355f TL |
936 | External Hyperlink Example |
937 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
938 | ||
939 | It is also possible to create a link to a section of the documentation and to | |
940 | have custom text appear in the body of the link. This is useful when it is more | |
941 | important to preserve the text of the sentence containing the link than it is | |
942 | to refer explicitly to the title of the section being linked to. | |
943 | ||
944 | For example, RST that links to the Sphinx Python Document Generator homepage | |
945 | and generates a sentence reading "Click here to learn more about Python | |
946 | Sphinx." looks like this: | |
947 | ||
948 | :: | |
949 | ||
950 | ``Click `here <https://www.sphinx-doc.org>`_ to learn more about Python | |
951 | Sphinx.`` | |
952 | ||
953 | And here it is, rendered: | |
954 | ||
955 | Click `here <https://www.sphinx-doc.org>`_ to learn more about Python Sphinx. | |
956 | ||
957 | Pay special attention to the underscore after the backtick. If you forget to | |
958 | include it and this is your first day working with RST, there's a chance that | |
959 | you'll spend all day wondering what went wrong without realizing that you | |
960 | omitted that underscore. Also, pay special attention to the space between the | |
961 | substitution text (in this case, "here") and the less-than bracket that sets | |
962 | the explicit link apart from the substition text. The link will not render | |
963 | properly without this space. | |
964 | ||
965 | Linking Customs | |
966 | ~~~~~~~~~~~~~~~ | |
967 | ||
968 | By a custom established when Ceph was still being developed by Inktank, | |
969 | contributors to the documentation of the Ceph project preferred to use the | |
970 | convention of putting ``.. _Link Text: ../path`` links at the bottom of the | |
971 | document and linking to them using references of the form ``:ref:`path```. This | |
972 | convention was preferred because it made the documents more readable in a | |
973 | command line interface. As of 2023, though, we have no preference for one over | |
974 | the other. Use whichever convention makes the text easier to read. | |
975 | ||
aee94f69 TL |
976 | Using a part of a sentence as a hyperlink, `like this <docs.ceph.com>`_, is |
977 | discouraged. The convention of writing "See X" is preferred. Here are some | |
978 | preferred formulations: | |
979 | ||
980 | #. For more information, see `docs.ceph.com <docs.ceph.com>`_. | |
981 | ||
982 | #. See `docs.ceph.com <docs.ceph.com>`_. | |
983 | ||
984 | ||
39ae355f TL |
985 | Quirks of ReStructured Text |
986 | --------------------------- | |
987 | ||
988 | External Links | |
989 | ~~~~~~~~~~~~~~ | |
990 | ||
991 | .. _external_link_with_inline_text: | |
992 | ||
aee94f69 TL |
993 | Use the formula immediately below to render links that direct the reader to |
994 | addresses external to the Ceph documentation: | |
39ae355f TL |
995 | |
996 | :: | |
997 | ||
998 | `inline text <http:www.foo.com>`_ | |
999 | ||
1000 | .. note:: Do not fail to include the space between the inline text and the | |
1001 | less-than sign. | |
1002 | ||
1003 | Do not fail to include the underscore after the final backtick. | |
1004 | ||
1005 | To link to addresses that are external to the Ceph documentation, include a | |
1006 | space between the inline text and the angle bracket that precedes the | |
aee94f69 TL |
1007 | external address. This is precisely the opposite of the convention for |
1008 | inline text that links to a location inside the Ceph documentation. See | |
1009 | :ref:`here <internal_link_with_inline_text>` for an exemplar of this | |
1010 | convention. | |
1011 | ||
1012 | If this seems inconsistent and confusing to you, then you're right. It is | |
1013 | inconsistent and confusing. | |
39ae355f TL |
1014 | |
1015 | See also ":ref:`External Hyperlink Example<start_external_hyperlink_example>`". | |
1016 | ||
1017 | Internal Links | |
1018 | ~~~~~~~~~~~~~~ | |
1019 | ||
1020 | To link to a section in the Ceph documentation, you must (1) define a target | |
1021 | link before the section and then (2) link to that target from another location | |
1022 | in the documentation. Here are the formulas for targets and links to those | |
1023 | targets: | |
1024 | ||
1025 | Target:: | |
1026 | ||
1027 | .. _target: | |
1028 | ||
1029 | Title of Targeted Section | |
1030 | ========================= | |
1031 | ||
1032 | Lorem ipsum... | |
1033 | ||
1034 | Link to target:: | |
1035 | ||
1036 | :ref:`target` | |
1037 | ||
1038 | .. _internal_link_with_inline_text: | |
1039 | ||
1040 | Link to target with inline text:: | |
1041 | ||
1042 | :ref:`inline text<target>` | |
1043 | ||
1044 | .. note:: | |
1045 | ||
1046 | There is no space between "inline text" and the angle bracket that | |
1047 | immediately follows it. This is precisely the opposite of :ref:`the | |
1048 | convention for inline text that links to a location outside of the Ceph | |
1049 | documentation<external_link_with_inline_text>`. If this seems inconsistent | |
1050 | and confusing to you, then you're right. It is inconsistent and confusing. | |
1051 | ||
1052 | Escaping Bold Characters within Words | |
1053 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1054 | ||
1055 | This section explains how to make certain letters within a word bold while | |
1056 | leaving the other letters in the word regular (non-bold). | |
1057 | ||
1058 | The following single-line paragraph provides an example of this: | |
1059 | ||
1060 | **C**\eph **F**\ile **S**\ystem. | |
1061 | ||
1062 | In ReStructured Text, the following formula will not work: | |
1063 | ||
1064 | :: | |
1065 | ||
1066 | **C**eph **F**ile **S**ystem | |
1067 | ||
1068 | The bolded notation must be turned off by means of the escape character (\\), as shown here: | |
1069 | ||
1070 | :: | |
1071 | ||
1072 | **C**\eph **F**\ile **S**\ystem | |
1073 | ||
1074 | .. _Python Sphinx: https://www.sphinx-doc.org | |
1075 | .. _restructuredText: http://docutils.sourceforge.net/rst.html | |
7c673cae FG |
1076 | .. _Fork and Pull: https://help.github.com/articles/using-pull-requests |
1077 | .. _github: http://github.com | |
1078 | .. _ditaa: http://ditaa.sourceforge.net/ | |
1079 | .. _Document Title: http://docutils.sourceforge.net/docs/user/rst/quickstart.html#document-title-subtitle | |
1080 | .. _Sections: http://docutils.sourceforge.net/docs/user/rst/quickstart.html#sections | |
11fdf7f2 | 1081 | .. _Cross referencing arbitrary locations: http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref |
7c673cae FG |
1082 | .. _The TOC tree: http://sphinx-doc.org/markup/toctree.html |
1083 | .. _Showing code examples: http://sphinx-doc.org/markup/code.html | |
1084 | .. _paragraph level markup: http://sphinx-doc.org/markup/para.html | |
1085 | .. _topic directive: http://docutils.sourceforge.net/docs/ref/rst/directives.html#topic |