Re: [PATCH 5/6] composefs: Add documentation

[Bagas Sanjaya]

On Mon, Nov 28, 2022 at 12:17:26PM +0100, Alexander Larsson wrote:
> This adds documentation about the composefs filesystem and
> how to use it.
> 

Nit: s/This adds/Add/
Also, please Cc: linux-doc list for documentation patches.

> +Given such a descriptor called "image.cfs" and a directory with files
> +called "/dir" you can mount it like:
> +
> +  mount -t composefs image.cfs -o basedir=/dir /mnt

What about using literal code block, like below?

---- >8 ----
diff --git a/Documentation/filesystems/composefs.rst b/Documentation/filesystems/composefs.rst
index a0d88cc9baf9fb..e1faaf0ca69181 100644
--- a/Documentation/filesystems/composefs.rst
+++ b/Documentation/filesystems/composefs.rst
@@ -22,7 +22,7 @@ file content from the filesystem by looking up that filename in a set
 of base directories.
 
 Given such a descriptor called "image.cfs" and a directory with files
-called "/dir" you can mount it like:
+called "/dir" you can mount it like::
 
   mount -t composefs image.cfs -o basedir=/dir /mnt
 

> +Composefs uses `fs-verity
> +<https://www.kernel.org/doc/Documentation/filesystems/fsverity.rst>`

Use :doc: for internal linking to other documentation:

---- >8 ----
diff --git a/Documentation/filesystems/composefs.rst b/Documentation/filesystems/composefs.rst
index 65a8c9889427b2..38dac5af117551 100644
--- a/Documentation/filesystems/composefs.rst
+++ b/Documentation/filesystems/composefs.rst
@@ -51,8 +51,7 @@ all mounts.
 Integrity validation
 ====================
 
-Composefs uses `fs-verity
-<https://www.kernel.org/doc/Documentation/filesystems/fsverity.rst>`
+Composefs uses :doc:`fs-verity <fsverity>`
 for integrity validation, and extends it by making the validation also
 apply to the directory metadata.  This happens on two levels,
 validation of the descriptor and validation of the backing files.

> +
> +Expected use-cases
> +=================
> +

Sphinx reported underline too short warning, so you need to match the underline
length with title text:

---- >8 ----
diff --git a/Documentation/filesystems/composefs.rst b/Documentation/filesystems/composefs.rst
index 75fbf14aeb3355..65a8c9889427b2 100644
--- a/Documentation/filesystems/composefs.rst
+++ b/Documentation/filesystems/composefs.rst
@@ -72,7 +72,7 @@ files. This means any (accidental or malicious) modification of the
 basedir will be detected at the time the file is used.
 
 Expected use-cases
-=================
+==================
 
 Container Image Storage
 ```````````````````````

> +Mount options
> +=============
> +
> +`basedir`: A colon separated list of directories to use as a base when resolving relative content paths.
> +`verity_check=[0,1,2]`: When to verify backing file fs-verity: 0 == never, 1 == if specified in image, 2 == always and require it in image.
> +`digest`: A fs-verity sha256 digest that the descriptor file must match. If set, `verity_check` defaults to 2.

Use definition list for list of options and its descriptions:

---- >8 ----
diff --git a/Documentation/filesystems/composefs.rst b/Documentation/filesystems/composefs.rst
index 38dac5af117551..a0d88cc9baf9fb 100644
--- a/Documentation/filesystems/composefs.rst
+++ b/Documentation/filesystems/composefs.rst
@@ -112,9 +112,17 @@ all directory metadata and file content is validated lazily at use.
 Mount options
 =============
 
-`basedir`: A colon separated list of directories to use as a base when resolving relative content paths.
-`verity_check=[0,1,2]`: When to verify backing file fs-verity: 0 == never, 1 == if specified in image, 2 == always and require it in image.
-`digest`: A fs-verity sha256 digest that the descriptor file must match. If set, `verity_check` defaults to 2.
+basedir
+    A colon separated list of directories to use as a base when resolving
+    relative content paths.
+
+verity_check=[0,1,2]
+    When to verify backing file fs-verity: 0 == never; 1 == if specified in
+    image; 2 == always and require it in image.
+
+digest
+    A fs-verity sha256 digest that the descriptor file must match. If set,
+    verity_check defaults to 2.
 
 
 Filesystem format

Finally, you need to add the documentation to table of contents for filesystem
documentation:

---- >8 ----
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index bee63d42e5eca0..9b7cf136755dce 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -75,6 +75,7 @@ Documentation for filesystem implementations.
    cifs/index
    ceph
    coda
+   composefs
    configfs
    cramfs
    dax
 
Thanks.

-- 
An old man doll... just what I always wanted! - Clara

Attachment: signature.asc
Description: PGP signature