[U-Boot] [PATCH 1/1] doc: add structure to Sphinx generated docs

Sun Jul 29 11:45:47 UTC 2018

Create separate html pages for linker lists, the serial subsystem,
and the EFI subsystem.

Add a table of content.

Signed-off-by: Heinrich Schuchardt <xypron.glpk at gmx.de>
---
 Documentation/efi.rst          |  16 +++++
 Documentation/index.rst        | 122 +++------------------------------
 Documentation/linker_lists.rst | 100 +++++++++++++++++++++++++++
 Documentation/serial.rst       |   7 ++
 MAINTAINERS                    |   1 +
 5 files changed, 132 insertions(+), 114 deletions(-)
 create mode 100644 Documentation/efi.rst
 create mode 100644 Documentation/linker_lists.rst
 create mode 100644 Documentation/serial.rst

diff --git a/Documentation/efi.rst b/Documentation/efi.rst
new file mode 100644
index 00000000000..51c1de24f84
--- /dev/null
+++ b/Documentation/efi.rst
@@ -0,0 +1,16 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+EFI subsystem
+=============
+
+Boot services
+-------------
+
+.. kernel-doc:: lib/efi_loader/efi_boottime.c
+   :internal:
+
+Runtime services
+----------------
+
+.. kernel-doc:: lib/efi_loader/efi_runtime.c
+   :internal:
diff --git a/Documentation/index.rst b/Documentation/index.rst
index a7b0ee4e87d..0353c10a4b0 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -1,117 +1,11 @@
-====================
-U-Boot Hacker Manual
-====================
+.. SPDX-License-Identifier: GPL-2.0+
 
-Linker-Generated Arrays
-=======================
+#######################
+U-Boot Developer Manual
+#######################
 
-A linker list is constructed by grouping together linker input
-sections, each containing one entry of the list. Each input section
-contains a constant initialized variable which holds the entry's
-content. Linker list input sections are constructed from the list
-and entry names, plus a prefix which allows grouping all lists
-together. Assuming _list and _entry are the list and entry names,
-then the corresponding input section name is
+.. toctree::
 
-::
-
-  .u_boot_list_ + 2_ + @_list + _2_ + @_entry
-
-and the C variable name is
-
-::
-
-  _u_boot_list + _2_ + @_list + _2_ + @_entry
-
-This ensures uniqueness for both input section and C variable name.
-
-Note that the names differ only in the first character, "." for the
-section and "_" for the variable, so that the linker cannot confuse
-section and symbol names. From now on, both names will be referred
-to as
-
-::
-
-  %u_boot_list_ + 2_ + @_list + _2_ + @_entry
-
-Entry variables need never be referred to directly.
-
-The naming scheme for input sections allows grouping all linker lists
-into a single linker output section and grouping all entries for a
-single list.
-
-Note the two '_2_' constant components in the names: their presence
-allows putting a start and end symbols around a list, by mapping
-these symbols to sections names with components "1" (before) and
-"3" (after) instead of "2" (within).
-Start and end symbols for a list can generally be defined as
-
-::
-
-  %u_boot_list_2_ + @_list + _1_...
-  %u_boot_list_2_ + @_list + _3_...
-
-Start and end symbols for the whole of the linker lists area can be
-defined as
-
-::
-
-  %u_boot_list_1_...
-  %u_boot_list_3_...
-
-Here is an example of the sorted sections which result from a list
-"array" made up of three entries : "first", "second" and "third",
-iterated at least once.
-
-::
-
-  .u_boot_list_2_array_1
-  .u_boot_list_2_array_2_first
-  .u_boot_list_2_array_2_second
-  .u_boot_list_2_array_2_third
-  .u_boot_list_2_array_3
-
-If lists must be divided into sublists (e.g. for iterating only on
-part of a list), one can simply give the list a name of the form
-'outer_2_inner', where 'outer' is the global list name and 'inner'
-is the sub-list name. Iterators for the whole list should use the
-global list name ("outer"); iterators for only a sub-list should use
-the full sub-list name ("outer_2_inner").
-
-Here is an example of the sections generated from a global list
-named "drivers", two sub-lists named "i2c" and "pci", and iterators
-defined for the whole list and each sub-list:
-
-::
-
-  %u_boot_list_2_drivers_1
-  %u_boot_list_2_drivers_2_i2c_1
-  %u_boot_list_2_drivers_2_i2c_2_first
-  %u_boot_list_2_drivers_2_i2c_2_first
-  %u_boot_list_2_drivers_2_i2c_2_second
-  %u_boot_list_2_drivers_2_i2c_2_third
-  %u_boot_list_2_drivers_2_i2c_3
-  %u_boot_list_2_drivers_2_pci_1
-  %u_boot_list_2_drivers_2_pci_2_first
-  %u_boot_list_2_drivers_2_pci_2_second
-  %u_boot_list_2_drivers_2_pci_2_third
-  %u_boot_list_2_drivers_2_pci_3
-  %u_boot_list_2_drivers_3
-
-.. kernel-doc:: include/linker_lists.h
-   :internal:
-
-Serial system
-=============
-
-.. kernel-doc:: drivers/serial/serial.c
-   :internal:
-
-The U-Boot EFI subsystem
-========================
-
-Boot services
--------------
-
-.. kernel-doc:: lib/efi_loader/efi_boottime.c
-   :internal:
+   efi
+   linker_lists
+   serial
diff --git a/Documentation/linker_lists.rst b/Documentation/linker_lists.rst
new file mode 100644
index 00000000000..72f514e0ac0
--- /dev/null
+++ b/Documentation/linker_lists.rst
@@ -0,0 +1,100 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Linker-Generated Arrays
+=======================
+
+A linker list is constructed by grouping together linker input
+sections, each containing one entry of the list. Each input section
+contains a constant initialized variable which holds the entry's
+content. Linker list input sections are constructed from the list
+and entry names, plus a prefix which allows grouping all lists
+together. Assuming _list and _entry are the list and entry names,
+then the corresponding input section name is
+
+::
+
+  .u_boot_list_ + 2_ + @_list + _2_ + @_entry
+
+and the C variable name is
+
+::
+
+  _u_boot_list + _2_ + @_list + _2_ + @_entry
+
+This ensures uniqueness for both input section and C variable name.
+
+Note that the names differ only in the first character, "." for the
+section and "_" for the variable, so that the linker cannot confuse
+section and symbol names. From now on, both names will be referred
+to as
+
+::
+
+  %u_boot_list_ + 2_ + @_list + _2_ + @_entry
+
+Entry variables need never be referred to directly.
+
+The naming scheme for input sections allows grouping all linker lists
+into a single linker output section and grouping all entries for a
+single list.
+
+Note the two '_2_' constant components in the names: their presence
+allows putting a start and end symbols around a list, by mapping
+these symbols to sections names with components "1" (before) and
+"3" (after) instead of "2" (within).
+Start and end symbols for a list can generally be defined as
+
+::
+
+  %u_boot_list_2_ + @_list + _1_...
+  %u_boot_list_2_ + @_list + _3_...
+
+Start and end symbols for the whole of the linker lists area can be
+defined as
+
+::
+
+  %u_boot_list_1_...
+  %u_boot_list_3_...
+
+Here is an example of the sorted sections which result from a list
+"array" made up of three entries : "first", "second" and "third",
+iterated at least once.
+
+::
+
+  .u_boot_list_2_array_1
+  .u_boot_list_2_array_2_first
+  .u_boot_list_2_array_2_second
+  .u_boot_list_2_array_2_third
+  .u_boot_list_2_array_3
+
+If lists must be divided into sublists (e.g. for iterating only on
+part of a list), one can simply give the list a name of the form
+'outer_2_inner', where 'outer' is the global list name and 'inner'
+is the sub-list name. Iterators for the whole list should use the
+global list name ("outer"); iterators for only a sub-list should use
+the full sub-list name ("outer_2_inner").
+
+Here is an example of the sections generated from a global list
+named "drivers", two sub-lists named "i2c" and "pci", and iterators
+defined for the whole list and each sub-list:
+
+::
+
+  %u_boot_list_2_drivers_1
+  %u_boot_list_2_drivers_2_i2c_1
+  %u_boot_list_2_drivers_2_i2c_2_first
+  %u_boot_list_2_drivers_2_i2c_2_first
+  %u_boot_list_2_drivers_2_i2c_2_second
+  %u_boot_list_2_drivers_2_i2c_2_third
+  %u_boot_list_2_drivers_2_i2c_3
+  %u_boot_list_2_drivers_2_pci_1
+  %u_boot_list_2_drivers_2_pci_2_first
+  %u_boot_list_2_drivers_2_pci_2_second
+  %u_boot_list_2_drivers_2_pci_2_third
+  %u_boot_list_2_drivers_2_pci_3
+  %u_boot_list_2_drivers_3
+
+.. kernel-doc:: include/linker_lists.h
+   :internal:
diff --git a/Documentation/serial.rst b/Documentation/serial.rst
new file mode 100644
index 00000000000..ed34e592a44
--- /dev/null
+++ b/Documentation/serial.rst
@@ -0,0 +1,7 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Serial system
+=============
+
+.. kernel-doc:: drivers/serial/serial.c
+   :internal:
diff --git a/MAINTAINERS b/MAINTAINERS
index c4f78d9e82d..a2cea8245d7 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -365,6 +365,7 @@ T:	git git://github.com/agraf/u-boot.git
 F:	doc/DocBook/efi.tmpl
 F:	doc/README.uefi
 F:	doc/README.iscsi
+F:	Documentation/efi.rst
 F:	include/capitalization.h
 F:	include/efi*
 F:	include/pe.h
-- 
2.18.0

