[PATCH 1/9] docs: Format lists of files better
Signed-off-by: Andrea Bolognani <abologna(a)redhat.com>
---
docs/api_extension.rst | 27 +++++++++++++++++----------
1 file changed, 17 insertions(+), 10 deletions(-)
diff --git a/docs/api_extension.rst b/docs/api_extension.rst
index 152e64487e..a42c82daca 100644
--- a/docs/api_extension.rst
+++ b/docs/api_extension.rst
@@ -73,14 +73,16 @@ The first task is to define the public API. If the new API involves
an
XML extension, you have to enhance the RelaxNG schema and document the
new elements or attributes:
-``src/conf/schemas/domaincommon.rng docs/formatdomain.rst``
+* ``src/conf/schemas/domaincommon.rng``
+* ``docs/formatdomain.rst``
If the API extension involves a new function, you have to add a
declaration in the public header, and arrange to export the function
name (symbol) so other programs can link against the libvirt library and
call the new function:
-``include/libvirt/libvirt-$MODULE.h.in src/libvirt_public.syms``
+* ``include/libvirt/libvirt-$MODULE.h.in``
+* ``src/libvirt_public.syms``
Please consult our `coding
style <coding-style.html#xml-element-and-attribute-naming>`__ guide on
@@ -108,7 +110,7 @@ creation of a new struct type to represent the new driver type.
The driver structs are defined in:
-``src/driver-$MODULE.h``
+* ``src/driver-$MODULE.h``
To define the internal API, first typedef the driver function prototype
and then add a new field for it to the relevant driver struct. Then,
@@ -142,7 +144,7 @@ driver implementation. In RFC 2119 vocabulary, this function:
The public API calls are implemented in:
-``src/libvirt-$MODULE.c``
+* ``src/libvirt-$MODULE.c``
Implementing the remote protocol
--------------------------------
@@ -156,7 +158,7 @@ Defining the wire protocol format
Defining the wire protocol involves making additions to:
-``src/remote/remote_protocol.x``
+* ``src/remote/remote_protocol.x``
First, create two new structs for each new function that you're adding
to the API. One struct describes the parameters to be passed to the
@@ -174,7 +176,11 @@ protocol code. This must be done on a Linux host using the GLibC
rpcgen
program. Other rpcgen versions may generate code which results in bogus
compile time warnings. This regenerates the following files:
-``src/remote/remote_daemon_dispatch_stubs.h src/remote/remote_daemon_dispatch.h
src/remote/remote_daemon_dispatch.c src/remote/remote_protocol.c
src/remote/remote_protocol.h``
+* ``src/remote/remote_daemon_dispatch_stubs.h``
+* ``src/remote/remote_daemon_dispatch.h``
+* ``src/remote/remote_daemon_dispatch.c``
+* ``src/remote/remote_protocol.c``
+* ``src/remote/remote_protocol.h``
Implement the RPC client
~~~~~~~~~~~~~~~~~~~~~~~~
@@ -182,7 +188,7 @@ Implement the RPC client
Implementing the RPC client uses the rpcgen generated .h files. The
remote method calls go in:
-``src/remote/remote_driver.c``
+* ``src/remote/remote_driver.c``
Each remote method invocation does the following:
@@ -202,7 +208,7 @@ matter of deserializing the parameters passed in from the remote
caller
and passing them to the corresponding internal API function. The server
side dispatchers are implemented in:
-``src/remote/remote_daemon_dispatch.c``
+* ``src/remote/remote_daemon_dispatch.c``
Again, this step uses the .h files generated by make rpcgen.
@@ -210,7 +216,7 @@ After all three pieces of the remote protocol are complete, and the
generated files have been updated, it will be necessary to update the
file:
-``src/remote_protocol-structs``
+* ``src/remote_protocol-structs``
This file should only have new lines added; modifications to existing
lines probably imply a backwards-incompatible API change.
@@ -246,7 +252,8 @@ those pieces in place you can write the function implementing the
virsh
command. Finally, you need to add the new command to the commands[]
array. The following files need changes:
-``tools/virsh-$MODULE.c tools/virsh.pod``
+* ``tools/virsh-$MODULE.c``
+* ``tools/virsh.pod``
Implement the driver methods
----------------------------
--
2.43.2