From 85ec5ff7cc5c0957284d26e7d34bfcc615f2373e Mon Sep 17 00:00:00 2001 From: Aceves Date: Wed, 10 Feb 2016 12:31:38 -0600 Subject: [PATCH] doc: Edit the heading markup Edited heading markup for consistancy. Change-Id: Ic91cea28427be92e82f1318821a6eead78467c52 Signed-off-by: Aceves --- doc/collaboration/documentation/code_blocks.rst | 6 +++--- doc/collaboration/documentation/cross.rst | 16 ++++++++-------- doc/collaboration/documentation/images.rst | 6 +++--- doc/collaboration/documentation/inline.rst | 2 +- doc/collaboration/documentation/tables.rst | 2 +- 5 files changed, 16 insertions(+), 16 deletions(-) diff --git a/doc/collaboration/documentation/code_blocks.rst b/doc/collaboration/documentation/code_blocks.rst index 6aee27cc582..3c0778a73c5 100644 --- a/doc/collaboration/documentation/code_blocks.rst +++ b/doc/collaboration/documentation/code_blocks.rst @@ -1,7 +1,7 @@ .. _code_examples: Code Examples -************* +############# Collaborating to the Zephyr Kernel is all about code. Therefore, your documentation must include code examples. The code examples can be @@ -22,7 +22,7 @@ Use these guidelines to insert code blocks to your documentation: * Treat all console commands that a user must use as code examples. Examples --------- +******** This is a code example included from a file in another directory. Only certain lines of the source file are included. Those lines of code are @@ -120,7 +120,7 @@ Renders as: Templates ---------- +********* We have included templates for a basic ``.. code-block::`` directive and for a ``.. literalinclude::`` directive. diff --git a/doc/collaboration/documentation/cross.rst b/doc/collaboration/documentation/cross.rst index 6934806709f..fe85dfff3f5 100644 --- a/doc/collaboration/documentation/cross.rst +++ b/doc/collaboration/documentation/cross.rst @@ -1,7 +1,7 @@ .. _cross: Cross References -**************** +################ Sphinx and ReST provide different methods to create both internal and external cross references. Use only the following methods to increase the @@ -10,7 +10,7 @@ consistency of the documents. .. _internal_cross: Internal Cross References -========================= +************************* An internal cross reference is a reference to a location within the Zephyr Project's documentation. Use explicit markup labels and the ``:ref:`` markup to @@ -62,8 +62,8 @@ Use the following templates to insert internal cross references properly. .. _label_of_target: - This Is a Heading - ----------------- + This Is a Level Three Heading + ============================= This creates a link to the :ref:`label_of_target` using the text of the heading. @@ -75,8 +75,8 @@ The template renders as: .. _label_of_target: -This Is a Heading ------------------ +This Is a Level Three Heading +============================= This creates a link to the :ref:`label_of_target` using the text of the heading. @@ -91,7 +91,7 @@ This creates a link to the :ref:`target ` using the word Sphinx builders that support cross references. Referencing In-code Documentation -================================= +********************************* We have integrated in-code documentation using Sphinx and :program:`Breath`. This integration allows us to cross reference functions, variables, macros @@ -114,7 +114,7 @@ reference to a documented code element. documented in the code following the :ref:`code`. External References -=================== +******************* External references or hyperlinks can be added easily with ReST. The allowed methods are explicit hyperlinks and hyperlinks with a separated target diff --git a/doc/collaboration/documentation/images.rst b/doc/collaboration/documentation/images.rst index 52dda2c3905..7af05f22a85 100644 --- a/doc/collaboration/documentation/images.rst +++ b/doc/collaboration/documentation/images.rst @@ -1,7 +1,7 @@ .. _images: Images -****** +###### Images grab the reader's attention and convey information that sometimes is difficult to explain using words alone. Well-planned @@ -46,7 +46,7 @@ Follow these guidelines when creating graphics for the Zephyr Project: fibers.svg` or :file:`nanokernel_fiber-1.png`. Examples -======== +******** These examples follow the guidelines and can be used used as reference. @@ -77,7 +77,7 @@ and linked to make identifying them easier. This screenshot shows a code comparison. Templates -========= +********* Use this template to add a figure to your documentation according to these guidelines. diff --git a/doc/collaboration/documentation/inline.rst b/doc/collaboration/documentation/inline.rst index e9f31a3e965..ba90d80797f 100644 --- a/doc/collaboration/documentation/inline.rst +++ b/doc/collaboration/documentation/inline.rst @@ -1,7 +1,7 @@ .. _inline: Inline Markup -************* +############# Sphinx supports a large number of inline markup elements. The documentation of the Zephyr OS only requires the use of the inline diff --git a/doc/collaboration/documentation/tables.rst b/doc/collaboration/documentation/tables.rst index 0e87841bdb9..7207ff61415 100644 --- a/doc/collaboration/documentation/tables.rst +++ b/doc/collaboration/documentation/tables.rst @@ -1,7 +1,7 @@ .. _rest_tables: Tables -****** +###### Tables must only be used for information that is either too numerous or too related for a list to be appropriate. The general rule of thumb is that the