binman: Incorporate entry documentation

Update this to avoid sphinx warnings and incorporate it into the new
documentaiton tree.

Signed-off-by: Simon Glass <sjg@chromium.org>

10 files changed, 87 insertions, 77 deletions

diff --git a/tools/binman/cmdline.py b/tools/binman/cmdline.py
index 0c0f48951f..95f9ba27fb 100644
--- a/tools/binman/cmdline.py
+++ b/tools/binman/cmdline.py
@@ -69,7 +69,7 @@ controlled by a description in the board device tree.'''
         default=False, help='Update the binman node with offset/size info')
 
     entry_parser = subparsers.add_parser('entry-docs',
-        help='Write out entry documentation (see README.entries)')
+        help='Write out entry documentation (see entries.rst)')
 
     list_parser = subparsers.add_parser('ls', help='List files in an image')
     list_parser.add_argument('-i', '--image', type=str, required=True,
diff --git a/tools/binman/README.entries b/tools/binman/entries.rst
index 0d9105e41c..2d79850c64 100644
--- a/tools/binman/README.entries
+++ b/tools/binman/entries.rst
@@ -106,7 +106,7 @@ is not used, it supports compression and storing ELF files.
 
 CBFS is used by coreboot as its way of orgnanising SPI-flash contents.
 
-The contents of the CBFS are defined by subnodes of the cbfs entry, e.g.:
+The contents of the CBFS are defined by subnodes of the cbfs entry, e.g.::
 
     cbfs {
         size = <0x100000>;
@@ -122,7 +122,7 @@ This creates a CBFS 1MB in size two files in it: u-boot.bin and u-boot.dtb.
 Note that the size is required since binman does not support calculating it.
 The contents of each entry is just what binman would normally provide if it
 were not a CBFS node. A blob type can be used to import arbitrary files as
-with the second subnode below:
+with the second subnode below::
 
     cbfs {
         size = <0x100000>;
@@ -168,7 +168,7 @@ cbfs-type:
         This is an ELF file that has been loaded (i.e. mapped to memory), so
         appears in the CBFS as a flat binary. The input file must be an ELF
         image, for example this puts "u-boot" (the ELF image) into a 'stage'
-        entry:
+        entry::
 
             cbfs {
                 size = <0x100000>;
@@ -178,7 +178,7 @@ cbfs-type:
                 };
             };
 
-        You can use your own ELF file with something like:
+        You can use your own ELF file with something like::
 
             cbfs {
                 size = <0x100000>;
@@ -211,7 +211,7 @@ not support other file types (e.g. payload), adding multiple files (like the
 particular offset in the CBFS and a few other things.
 
 Of course binman can create images containing multiple CBFSs, simply by
-defining these in the binman config:
+defining these in the binman config::
 
 
     binman {
@@ -279,24 +279,24 @@ sizes are included.
 Note that the -u option must be provided to ensure that binman updates the
 FDT with the position of each entry.
 
-Example output for a simple image with U-Boot and an FDT map:
+Example output for a simple image with U-Boot and an FDT map::
 
-/ {
-    image-name = "binman";
-    size = <0x00000112>;
-    image-pos = <0x00000000>;
-    offset = <0x00000000>;
-    u-boot {
-        size = <0x00000004>;
+    / {
+        image-name = "binman";
+        size = <0x00000112>;
         image-pos = <0x00000000>;
         offset = <0x00000000>;
+        u-boot {
+            size = <0x00000004>;
+            image-pos = <0x00000000>;
+            offset = <0x00000000>;
+        };
+        fdtmap {
+            size = <0x0000010e>;
+            image-pos = <0x00000004>;
+            offset = <0x00000004>;
+        };
     };
-    fdtmap {
-        size = <0x0000010e>;
-        image-pos = <0x00000004>;
-        offset = <0x00000004>;
-    };
-};
 
 If allow-repack is used then 'orig-offset' and 'orig-size' properties are
 added as necessary. See the binman README.
@@ -344,7 +344,7 @@ input provided.
 Nodes for the FIT should be written out in the binman configuration just as
 they would be in a file passed to mkimage.
 
-For example, this creates an image containing a FIT with U-Boot SPL:
+For example, this creates an image containing a FIT with U-Boot SPL::
 
     binman {
         fit {
@@ -374,7 +374,7 @@ that you want to generates nodes for two files: file1.dtb and file2.dtb
 The fit,fdt-list property (see above) indicates that of-list should be used.
 If the property is missing you will get an error.
 
-Then add a 'generator node', a node with a name starting with '@':
+Then add a 'generator node', a node with a name starting with '@'::
 
     images {
         @fdt-SEQ {
@@ -389,7 +389,7 @@ files. All the properties you specify will be included in the node. This
 node acts like a template to generate the nodes. The generator node itself
 does not appear in the output - it is replaced with what binman generates.
 
-You can create config nodes in a similar way:
+You can create config nodes in a similar way::
 
     configurations {
         default = "@config-DEFAULT-SEQ";
@@ -406,8 +406,10 @@ each of your two files.
 
 Available substitutions for '@' nodes are:
 
-    SEQ    Sequence number of the generated fdt (1, 2, ...)
-    NAME   Name of the dtb as provided (i.e. without adding '.dtb')
+SEQ:
+    Sequence number of the generated fdt (1, 2, ...)
+NAME
+    Name of the dtb as provided (i.e. without adding '.dtb')
 
 Note that if no devicetree files are provided (with '-a of-list' as above)
 then no nodes will be generated.
@@ -416,10 +418,11 @@ The 'default' property, if present, will be automatically set to the name
 if of configuration whose devicetree matches the 'default-dt' entry
 argument, e.g. with '-a default-dt=sun50i-a64-pine64-lts'.
 
-Available substitutions for '@' property values are:
+Available substitutions for '@' property values are
 
-    DEFAULT-SEQ  Sequence number of the default fdt,as provided by the
-                 'default-dt' entry argument
+DEFAULT-SEQ:
+    Sequence number of the default fdt,as provided by the 'default-dt' entry
+    argument
 
 Properties (in the 'fit' node itself):
     fit,external-offset: Indicates that the contents of the FIT are external
@@ -633,10 +636,10 @@ Each subnode describes an entry which is placed into the IFWFI with a given
 sub-partition (and optional entry name).
 
 Properties for subnodes:
-    ifwi-subpart - sub-parition to put this entry into, e.g. "IBBP"
-    ifwi-entry - entry name t use, e.g. "IBBL"
-    ifwi-replace - if present, indicates that the item should be replaced
-        in the IFWI. Otherwise it is added.
+    - ifwi-subpart: sub-parition to put this entry into, e.g. "IBBP"
+    - ifwi-entry: entry name t use, e.g. "IBBL"
+    - ifwi-replace: if present, indicates that the item should be replaced
+      in the IFWI. Otherwise it is added.
 
 See README.x86 for information about x86 binary blobs.
 
@@ -726,7 +729,7 @@ Properties / Entry arguments:
     - args: Other arguments to pass
 
 The data passed to mkimage is collected from subnodes of the mkimage node,
-e.g.:
+e.g.::
 
     mkimage {
         args = "-n test -T imximage";
@@ -766,11 +769,13 @@ This entry holds firmware for an external platform-specific coprocessor.
 Entry: section: Entry that contains other entries
 -------------------------------------------------
 
-Properties / Entry arguments: (see binman README for more information)
+Properties / Entry arguments: (see binman README for more information):
     pad-byte: Pad byte to use when padding
     sort-by-offset: True if entries should be sorted by offset, False if
-        they must be in-order in the device tree description
+    they must be in-order in the device tree description
+
     end-at-4gb: Used to build an x86 ROM which ends at 4GB (2^32)
+
     skip-at-start: Number of bytes before the first entry starts. These
         effectively adjust the starting offset of entries. For example,
         if this is 16, then the first entry would start at 16. An entry
@@ -808,7 +813,7 @@ Properties / Entry arguments:
     <text>: The text to place in the entry (overrides the above mechanism).
         This is useful when the text is constant.
 
-Example node:
+Example node::
 
     text {
         size = <50>;
@@ -821,7 +826,7 @@ You can then use:
 
 and binman will insert that string into the entry.
 
-It is also possible to put the string directly in the node:
+It is also possible to put the string directly in the node::
 
     text {
         size = <8>;
@@ -829,7 +834,7 @@ It is also possible to put the string directly in the node:
         message = "a message directly in the node"
     };
 
-or just:
+or just::
 
     text {
         size = <8>;
diff --git a/tools/binman/etype/cbfs.py b/tools/binman/etype/cbfs.py
index 6cdbaa085f..baf9c3e45b 100644
--- a/tools/binman/etype/cbfs.py
+++ b/tools/binman/etype/cbfs.py
@@ -22,7 +22,7 @@ class Entry_cbfs(Entry):
 
     CBFS is used by coreboot as its way of orgnanising SPI-flash contents.
 
-    The contents of the CBFS are defined by subnodes of the cbfs entry, e.g.:
+    The contents of the CBFS are defined by subnodes of the cbfs entry, e.g.::
 
         cbfs {
             size = <0x100000>;
@@ -38,7 +38,7 @@ class Entry_cbfs(Entry):
     Note that the size is required since binman does not support calculating it.
     The contents of each entry is just what binman would normally provide if it
     were not a CBFS node. A blob type can be used to import arbitrary files as
-    with the second subnode below:
+    with the second subnode below::
 
         cbfs {
             size = <0x100000>;
@@ -84,7 +84,7 @@ class Entry_cbfs(Entry):
             This is an ELF file that has been loaded (i.e. mapped to memory), so
             appears in the CBFS as a flat binary. The input file must be an ELF
             image, for example this puts "u-boot" (the ELF image) into a 'stage'
-            entry:
+            entry::
 
                 cbfs {
                     size = <0x100000>;
@@ -94,7 +94,7 @@ class Entry_cbfs(Entry):
                     };
                 };
 
-            You can use your own ELF file with something like:
+            You can use your own ELF file with something like::
 
                 cbfs {
                     size = <0x100000>;
@@ -127,7 +127,7 @@ class Entry_cbfs(Entry):
     particular offset in the CBFS and a few other things.
 
     Of course binman can create images containing multiple CBFSs, simply by
-    defining these in the binman config:
+    defining these in the binman config::
 
 
         binman {
diff --git a/tools/binman/etype/fdtmap.py b/tools/binman/etype/fdtmap.py
index 6ca88a100e..2339feeba8 100644
--- a/tools/binman/etype/fdtmap.py
+++ b/tools/binman/etype/fdtmap.py
@@ -53,24 +53,24 @@ class Entry_fdtmap(Entry):
     Note that the -u option must be provided to ensure that binman updates the
     FDT with the position of each entry.
 
-    Example output for a simple image with U-Boot and an FDT map:
-
-    / {
-        image-name = "binman";
-        size = <0x00000112>;
-        image-pos = <0x00000000>;
-        offset = <0x00000000>;
-        u-boot {
-            size = <0x00000004>;
+    Example output for a simple image with U-Boot and an FDT map::
+
+        / {
+            image-name = "binman";
+            size = <0x00000112>;
             image-pos = <0x00000000>;
             offset = <0x00000000>;
+            u-boot {
+                size = <0x00000004>;
+                image-pos = <0x00000000>;
+                offset = <0x00000000>;
+            };
+            fdtmap {
+                size = <0x0000010e>;
+                image-pos = <0x00000004>;
+                offset = <0x00000004>;
+            };
         };
-        fdtmap {
-            size = <0x0000010e>;
-            image-pos = <0x00000004>;
-            offset = <0x00000004>;
-        };
-    };
 
     If allow-repack is used then 'orig-offset' and 'orig-size' properties are
     added as necessary. See the binman README.
diff --git a/tools/binman/etype/fit.py b/tools/binman/etype/fit.py
index 1a7cbd7cec..c4fa711b85 100644
--- a/tools/binman/etype/fit.py
+++ b/tools/binman/etype/fit.py
@@ -22,7 +22,7 @@ class Entry_fit(Entry):
     Nodes for the FIT should be written out in the binman configuration just as
     they would be in a file passed to mkimage.
 
-    For example, this creates an image containing a FIT with U-Boot SPL:
+    For example, this creates an image containing a FIT with U-Boot SPL::
 
         binman {
             fit {
@@ -52,7 +52,7 @@ class Entry_fit(Entry):
     The fit,fdt-list property (see above) indicates that of-list should be used.
     If the property is missing you will get an error.
 
-    Then add a 'generator node', a node with a name starting with '@':
+    Then add a 'generator node', a node with a name starting with '@'::
 
         images {
             @fdt-SEQ {
@@ -67,7 +67,7 @@ class Entry_fit(Entry):
     node acts like a template to generate the nodes. The generator node itself
     does not appear in the output - it is replaced with what binman generates.
 
-    You can create config nodes in a similar way:
+    You can create config nodes in a similar way::
 
         configurations {
             default = "@config-DEFAULT-SEQ";
@@ -84,8 +84,10 @@ class Entry_fit(Entry):
 
     Available substitutions for '@' nodes are:
 
-        SEQ    Sequence number of the generated fdt (1, 2, ...)
-        NAME   Name of the dtb as provided (i.e. without adding '.dtb')
+    SEQ:
+        Sequence number of the generated fdt (1, 2, ...)
+    NAME
+        Name of the dtb as provided (i.e. without adding '.dtb')
 
     Note that if no devicetree files are provided (with '-a of-list' as above)
     then no nodes will be generated.
@@ -94,10 +96,11 @@ class Entry_fit(Entry):
     if of configuration whose devicetree matches the 'default-dt' entry
     argument, e.g. with '-a default-dt=sun50i-a64-pine64-lts'.
 
-    Available substitutions for '@' property values are:
+    Available substitutions for '@' property values are
 
-        DEFAULT-SEQ  Sequence number of the default fdt,as provided by the
-                     'default-dt' entry argument
+    DEFAULT-SEQ:
+        Sequence number of the default fdt,as provided by the 'default-dt' entry
+        argument
 
     Properties (in the 'fit' node itself):
         fit,external-offset: Indicates that the contents of the FIT are external
diff --git a/tools/binman/etype/intel_ifwi.py b/tools/binman/etype/intel_ifwi.py
index 1a0e481c19..c2ede641aa 100644
--- a/tools/binman/etype/intel_ifwi.py
+++ b/tools/binman/etype/intel_ifwi.py
@@ -37,10 +37,10 @@ class Entry_intel_ifwi(Entry_blob_ext):
     sub-partition (and optional entry name).
 
     Properties for subnodes:
-        ifwi-subpart - sub-parition to put this entry into, e.g. "IBBP"
-        ifwi-entry - entry name t use, e.g. "IBBL"
-        ifwi-replace - if present, indicates that the item should be replaced
-            in the IFWI. Otherwise it is added.
+        - ifwi-subpart: sub-parition to put this entry into, e.g. "IBBP"
+        - ifwi-entry: entry name t use, e.g. "IBBL"
+        - ifwi-replace: if present, indicates that the item should be replaced
+          in the IFWI. Otherwise it is added.
 
     See README.x86 for information about x86 binary blobs.
     """
diff --git a/tools/binman/etype/mkimage.py b/tools/binman/etype/mkimage.py
index 8fddc88118..f8c491d5d0 100644
--- a/tools/binman/etype/mkimage.py
+++ b/tools/binman/etype/mkimage.py
@@ -19,7 +19,7 @@ class Entry_mkimage(Entry):
         - args: Other arguments to pass
 
     The data passed to mkimage is collected from subnodes of the mkimage node,
-    e.g.:
+    e.g.::
 
         mkimage {
             args = "-n test -T imximage";
diff --git a/tools/binman/etype/section.py b/tools/binman/etype/section.py
index 2f862bddf0..cce1500b4e 100644
--- a/tools/binman/etype/section.py
+++ b/tools/binman/etype/section.py
@@ -22,11 +22,13 @@ from patman.tools import ToHexSize
 class Entry_section(Entry):
     """Entry that contains other entries
 
-    Properties / Entry arguments: (see binman README for more information)
+    Properties / Entry arguments: (see binman README for more information):
         pad-byte: Pad byte to use when padding
         sort-by-offset: True if entries should be sorted by offset, False if
-            they must be in-order in the device tree description
+        they must be in-order in the device tree description
+
         end-at-4gb: Used to build an x86 ROM which ends at 4GB (2^32)
+
         skip-at-start: Number of bytes before the first entry starts. These
             effectively adjust the starting offset of entries. For example,
             if this is 16, then the first entry would start at 16. An entry
diff --git a/tools/binman/etype/text.py b/tools/binman/etype/text.py
index a69c2a4ec4..45dfcc401e 100644
--- a/tools/binman/etype/text.py
+++ b/tools/binman/etype/text.py
@@ -25,7 +25,7 @@ class Entry_text(Entry):
         <text>: The text to place in the entry (overrides the above mechanism).
             This is useful when the text is constant.
 
-    Example node:
+    Example node::
 
         text {
             size = <50>;
@@ -38,7 +38,7 @@ class Entry_text(Entry):
 
     and binman will insert that string into the entry.
 
-    It is also possible to put the string directly in the node:
+    It is also possible to put the string directly in the node::
 
         text {
             size = <8>;
@@ -46,7 +46,7 @@ class Entry_text(Entry):
             message = "a message directly in the node"
         };
 
-    or just:
+    or just::
 
         text {
             size = <8>;
diff --git a/tools/binman/setup.py b/tools/binman/setup.py
index 2dad43d493..5ed94abdaf 100644
--- a/tools/binman/setup.py
+++ b/tools/binman/setup.py
@@ -7,6 +7,6 @@ setup(name='binman',
       scripts=['binman'],
       packages=['binman', 'binman.etype'],
       package_dir={'binman': ''},
-      package_data={'binman': ['README.rst', 'README.entries']},
+      package_data={'binman': ['README.rst', 'entries.rst']},
       classifiers=['Environment :: Console',
                    'Topic :: Software Development :: Embedded Systems'])