[PATCH 0/2] docs/filesystems:fixes two build warnings

[PATCH 0/2] docs/filesystems:fixes two build warnings

[Yanteng Si]

This series of patches fix some warnings:

linux-next/Documentation/filesystems/cifs/cifsd.rst:3: WARNING: Title overline too short.

=========================
CIFSD - SMB3 Kernel Server
=========================

linux-next/Documentation/filesystems/cifs/cifsd.rst: WARNING: document isn't included in any toctree

Yanteng Si(2):

docs: filesystems: cifsd: fix document title markup
docs: filesystems: add cifs to the index file

Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
Documentation/filesystems/cifs/cifsd.rst |  4 ++--
Documentation/filesystems/cifs/index.rst | 12 ++++++++++++
Documentation/filesystems/index.rst      |  2 +-
3 files changed, 15 insertions(+), 3 deletions(-)

[PATCH 1/2] docs: filesystems: cifsd: fix document title markup

[Yanteng Si]

As warned by sphinx:

linux-next/Documentation/filesystems/cifs/cifsd.rst:3: WARNING:
Title overline too short.

=========================
CIFSD - SMB3 Kernel Server
=========================

so,just increase it!
---
 Documentation/filesystems/cifs/cifsd.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/filesystems/cifs/cifsd.rst b/Documentation/filesystems/cifs/cifsd.rst
index e0c33d03f290..af3589da6923 100644
--- a/Documentation/filesystems/cifs/cifsd.rst
+++ b/Documentation/filesystems/cifs/cifsd.rst
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0
 
-=========================
+==========================
 CIFSD - SMB3 Kernel Server
-=========================
+==========================
 
 CIFSD is a linux kernel server which implements SMB3 protocol in kernel space
 for sharing files over network.
-- 
2.25.1

[PATCH 2/2] docs: filesystems: add cifs to the index file

[Yanteng Si]

    Filesystems has a new cifs folder. Add it to the index file.
    Should address this warning:

	linux-next/Documentation/filesystems/cifs/cifsd.rst: WARNING:
	document isn't included in any toctree
---
 Documentation/filesystems/cifs/index.rst | 12 ++++++++++++
 Documentation/filesystems/index.rst      |  2 +-
 2 files changed, 13 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/filesystems/cifs/index.rst

diff --git a/Documentation/filesystems/cifs/index.rst b/Documentation/filesystems/cifs/index.rst
new file mode 100644
index 000000000000..b4a487e9adff
--- /dev/null
+++ b/Documentation/filesystems/cifs/index.rst
@@ -0,0 +1,12 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====
+CIFS
+====
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   cifsd
+   cifsroot
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index d4853cb919d2..bdba80ae2bb1 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -72,7 +72,7 @@ Documentation for filesystem implementations.
    befs
    bfs
    btrfs
-   cifs/cifsroot
+   cifs/index
    ceph
    coda
    configfs
-- 
2.25.1

RE: [PATCH 1/2] docs: filesystems: cifsd: fix document title markup

[Namjae Jeon]

Hi Yanteng,

Thanks for your patch.
I have already applied the patch to fix this warning to steve's tree.

https://github.com/smfrench/smb3-kernel/commit/801019d874df84f5fa8d21148c2a82edc80785da

Thanks!
> As warned by sphinx:
> 
> linux-next/Documentation/filesystems/cifs/cifsd.rst:3: WARNING:
> Title overline too short.
> 
> =========================
> CIFSD - SMB3 Kernel Server
> =========================
> 
> so,just increase it!
> ---
>  Documentation/filesystems/cifs/cifsd.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/filesystems/cifs/cifsd.rst b/Documentation/filesystems/cifs/cifsd.rst
> index e0c33d03f290..af3589da6923 100644
> --- a/Documentation/filesystems/cifs/cifsd.rst
> +++ b/Documentation/filesystems/cifs/cifsd.rst
> @@ -1,8 +1,8 @@
>  .. SPDX-License-Identifier: GPL-2.0
> 
> -=========================
> +==========================
>  CIFSD - SMB3 Kernel Server
> -=========================
> +==========================
> 
>  CIFSD is a linux kernel server which implements SMB3 protocol in kernel space  for sharing files over
> network.
> --
> 2.25.1

RE: [PATCH 2/2] docs: filesystems: add cifs to the index file

[Namjae Jeon]

>     Filesystems has a new cifs folder. Add it to the index file.
>     Should address this warning:
> 
> 	linux-next/Documentation/filesystems/cifs/cifsd.rst: WARNING:
> 	document isn't included in any toctree
> ---
>  Documentation/filesystems/cifs/index.rst | 12 ++++++++++++
>  Documentation/filesystems/index.rst      |  2 +-
>  2 files changed, 13 insertions(+), 1 deletion(-)  create mode 100644
> Documentation/filesystems/cifs/index.rst
> 
> diff --git a/Documentation/filesystems/cifs/index.rst b/Documentation/filesystems/cifs/index.rst
> new file mode 100644
> index 000000000000..b4a487e9adff
> --- /dev/null
> +++ b/Documentation/filesystems/cifs/index.rst
> @@ -0,0 +1,12 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +====
> +CIFS
> +====
> +
> +.. toctree::
> +   :maxdepth: 2
> +   :numbered:
Could you please explain what :maxdepth and :numbered are ?

Thanks!
> +
> +   cifsd
> +   cifsroot
> diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
> index d4853cb919d2..bdba80ae2bb1 100644
> --- a/Documentation/filesystems/index.rst
> +++ b/Documentation/filesystems/index.rst
> @@ -72,7 +72,7 @@ Documentation for filesystem implementations.
>     befs
>     bfs
>     btrfs
> -   cifs/cifsroot
> +   cifs/index
>     ceph
>     coda
>     configfs
> --
> 2.25.1

Re: RE: [PATCH 2/2] docs: filesystems: add cifs to the index file

[司延腾]

Sorry, I copied an index as a base from somewhere else and modified it, obviously I didn't do a very nice job and this will cause problems for future developers. Just keep the defaults, can I delete them in v2?
Thanks!

Yanteng

"Namjae Jeon" <namjae.jeon@samsung.com>写道：
&gt; &gt;     Filesystems has a new cifs folder. Add it to the index file.
&gt; &gt;     Should address this warning:
&gt; &gt; 
&gt; &gt;  linux-next/Documentation/filesystems/cifs/cifsd.rst: WARNING:
&gt; &gt;  document isn't included in any toctree
&gt; &gt; ---
&gt; &gt;  Documentation/filesystems/cifs/index.rst | 12 ++++++++++++
&gt; &gt;  Documentation/filesystems/index.rst      |  2 +-
&gt; &gt;  2 files changed, 13 insertions(+), 1 deletion(-)  create mode 100644
&gt; &gt; Documentation/filesystems/cifs/index.rst
&gt; &gt; 
&gt; &gt; diff --git a/Documentation/filesystems/cifs/index.rst b/Documentation/filesystems/cifs/index.rst
&gt; &gt; new file mode 100644
&gt; &gt; index 000000000000..b4a487e9adff
&gt; &gt; --- /dev/null
&gt; &gt; +++ b/Documentation/filesystems/cifs/index.rst
&gt; &gt; @@ -0,0 +1,12 @@
&gt; &gt; +.. SPDX-License-Identifier: GPL-2.0
&gt; &gt; +
&gt; &gt; +====
&gt; &gt; +CIFS
&gt; &gt; +====
&gt; &gt; +
&gt; &gt; +.. toctree::
&gt; &gt; +   :maxdepth: 2
&gt; &gt; +   :numbered:
&gt; Could you please explain what :maxdepth and :numbered are ?
&gt; 
&gt; Thanks!
&gt; &gt; +
&gt; &gt; +   cifsd
&gt; &gt; +   cifsroot
&gt; &gt; diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
&gt; &gt; index d4853cb919d2..bdba80ae2bb1 100644
&gt; &gt; --- a/Documentation/filesystems/index.rst
&gt; &gt; +++ b/Documentation/filesystems/index.rst
&gt; &gt; @@ -72,7 +72,7 @@ Documentation for filesystem implementations.
&gt; &gt;     befs
&gt; &gt;     bfs
&gt; &gt;     btrfs
&gt; &gt; -   cifs/cifsroot
&gt; &gt; +   cifs/index
&gt; &gt;     ceph
&gt; &gt;     coda
&gt; &gt;     configfs
&gt; &gt; --
&gt; &gt; 2.25.1
&gt;


</namjae.jeon@samsung.com>

RE: RE: [PATCH 2/2] docs: filesystems: add cifs to the index file

[Namjae Jeon]

> Sorry, I copied an index as a base from somewhere else and modified it, obviously I didn't do a very
> nice job and this will cause problems for future developers. Just keep the defaults, can I delete them
> in v2?
Is it really right to delete them? First we have to know what they mean.
When I see Documentation/filesystems/nfs/index.st, :maxdepth is set to 1.
Can you take a look more ?

> Thanks!
> 
> Yanteng
> 
> "Namjae Jeon" <namjae.jeon@samsung.com>写道：
> &gt; &gt;     Filesystems has a new cifs folder. Add it to the index file.
> &gt; &gt;     Should address this warning:
> &gt; &gt;
> &gt; &gt;  linux-next/Documentation/filesystems/cifs/cifsd.rst: WARNING:
> &gt; &gt;  document isn't included in any toctree &gt; &gt; --- &gt; &gt;
> Documentation/filesystems/cifs/index.rst | 12 ++++++++++++
> &gt; &gt;  Documentation/filesystems/index.rst      |  2 +-
> &gt; &gt;  2 files changed, 13 insertions(+), 1 deletion(-)  create mode 100644 &gt; &gt;
> Documentation/filesystems/cifs/index.rst
> &gt; &gt;
> &gt; &gt; diff --git a/Documentation/filesystems/cifs/index.rst
> b/Documentation/filesystems/cifs/index.rst
> &gt; &gt; new file mode 100644
> &gt; &gt; index 000000000000..b4a487e9adff &gt; &gt; --- /dev/null &gt; &gt; +++
> b/Documentation/filesystems/cifs/index.rst
> &gt; &gt; @@ -0,0 +1,12 @@
> &gt; &gt; +.. SPDX-License-Identifier: GPL-2.0 &gt; &gt; + &gt; &gt; +==== &gt; &gt; +CIFS &gt; &gt;
> +==== &gt; &gt; + &gt; &gt; +.. toctree::
> &gt; &gt; +   :maxdepth: 2
> &gt; &gt; +   :numbered:
> &gt; Could you please explain what :maxdepth and :numbered are ?
> &gt;
> &gt; Thanks!
> &gt; &gt; +
> &gt; &gt; +   cifsd
> &gt; &gt; +   cifsroot
> &gt; &gt; diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
> &gt; &gt; index d4853cb919d2..bdba80ae2bb1 100644 &gt; &gt; --- a/Documentation/filesystems/index.rst
> &gt; &gt; +++ b/Documentation/filesystems/index.rst
> &gt; &gt; @@ -72,7 +72,7 @@ Documentation for filesystem implementations.
> &gt; &gt;     befs
> &gt; &gt;     bfs
> &gt; &gt;     btrfs
> &gt; &gt; -   cifs/cifsroot
> &gt; &gt; +   cifs/index
> &gt; &gt;     ceph
> &gt; &gt;     coda
> &gt; &gt;     configfs
> &gt; &gt; --
> &gt; &gt; 2.25.1
> &gt;
> 
> 
> </namjae.jeon@samsung.com>

Re: RE: RE: [PATCH 2/2] docs: filesystems: add cifs to the index file

[司延腾]

Thank you! In the past two days I have consulted not only other indexes, but also the Sphinx manual.  In the meantime I have done a lot of experimentation. Now I am convinced that: ":maxdepth：1" is appropriate; ":numbered" is not needed.
Thanks！

Yanteng
> -----原始邮件-----
&gt; 发件人: "Namjae Jeon" <namjae.jeon@samsung.com>
&gt; 发送时间: 2021-03-19 11:35:39 (星期五)
&gt; 收件人: "'司延腾'" <siyanteng@loongson.cn>
&gt; 抄送: mchehab+huawei@kernel.org, "'Steve French'" <stfrench@microsoft.com>, "'Gibeom Kim'" <gibeomii.kim@samsung.com>, linux-doc@vger.kernel.org, "'Huacai chen'" <chenhuacai@gmail.com>, siyanteng@gmail.com, "'Jonathan
&gt;  Corbet'" <corbet@lwn.net>
&gt; 主题: RE: RE: [PATCH 2/2]  docs: filesystems: add cifs to the index file
&gt; 
&gt; &gt; Sorry, I copied an index as a base from somewhere else and modified it, obviously I didn't do a very
&gt; &gt; nice job and this will cause problems for future developers. Just keep the defaults, can I delete them
&gt; &gt; in v2?
&gt; Is it really right to delete them? First we have to know what they mean.
&gt; When I see Documentation/filesystems/nfs/index.st, :maxdepth is set to 1.
&gt; Can you take a look more ?
&gt; 
&gt; &gt; Thanks!
&gt; &gt; 
&gt; &gt; Yanteng
&gt; &gt; 
&gt; &gt; "Namjae Jeon" <namjae.jeon@samsung.com>写道：
&gt; &gt; &gt; &gt;     Filesystems has a new cifs folder. Add it to the index file.
&gt; &gt; &gt; &gt;     Should address this warning:
&gt; &gt; &gt; &gt;
&gt; &gt; &gt; &gt;  linux-next/Documentation/filesystems/cifs/cifsd.rst: WARNING:
&gt; &gt; &gt; &gt;  document isn't included in any toctree &gt; &gt; --- &gt; &gt;
&gt; &gt; Documentation/filesystems/cifs/index.rst | 12 ++++++++++++
&gt; &gt; &gt; &gt;  Documentation/filesystems/index.rst      |  2 +-
&gt; &gt; &gt; &gt;  2 files changed, 13 insertions(+), 1 deletion(-)  create mode 100644 &gt; &gt;
&gt; &gt; Documentation/filesystems/cifs/index.rst
&gt; &gt; &gt; &gt;
&gt; &gt; &gt; &gt; diff --git a/Documentation/filesystems/cifs/index.rst
&gt; &gt; b/Documentation/filesystems/cifs/index.rst
&gt; &gt; &gt; &gt; new file mode 100644
&gt; &gt; &gt; &gt; index 000000000000..b4a487e9adff &gt; &gt; --- /dev/null &gt; &gt; +++
&gt; &gt; b/Documentation/filesystems/cifs/index.rst
&gt; &gt; &gt; &gt; @@ -0,0 +1,12 @@
&gt; &gt; &gt; &gt; +.. SPDX-License-Identifier: GPL-2.0 &gt; &gt; + &gt; &gt; +==== &gt; &gt; +CIFS &gt; &gt;
&gt; &gt; +==== &gt; &gt; + &gt; &gt; +.. toctree::
&gt; &gt; &gt; &gt; +   :maxdepth: 2
&gt; &gt; &gt; &gt; +   :numbered:
&gt; &gt; &gt; Could you please explain what :maxdepth and :numbered are ?
&gt; &gt; &gt;
&gt; &gt; &gt; Thanks!
&gt; &gt; &gt; &gt; +
&gt; &gt; &gt; &gt; +   cifsd
&gt; &gt; &gt; &gt; +   cifsroot
&gt; &gt; &gt; &gt; diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
&gt; &gt; &gt; &gt; index d4853cb919d2..bdba80ae2bb1 100644 &gt; &gt; --- a/Documentation/filesystems/index.rst
&gt; &gt; &gt; &gt; +++ b/Documentation/filesystems/index.rst
&gt; &gt; &gt; &gt; @@ -72,7 +72,7 @@ Documentation for filesystem implementations.
&gt; &gt; &gt; &gt;     befs
&gt; &gt; &gt; &gt;     bfs
&gt; &gt; &gt; &gt;     btrfs
&gt; &gt; &gt; &gt; -   cifs/cifsroot
&gt; &gt; &gt; &gt; +   cifs/index
&gt; &gt; &gt; &gt;     ceph
&gt; &gt; &gt; &gt;     coda
&gt; &gt; &gt; &gt;     configfs
&gt; &gt; &gt; &gt; --
&gt; &gt; &gt; &gt; 2.25.1
&gt; &gt; &gt;
&gt; &gt; 
&gt; &gt; 
&gt; &gt; </namjae.jeon@samsung.com>
&gt; 
&gt;


</corbet@lwn.net></chenhuacai@gmail.com></gibeomii.kim@samsung.com></stfrench@microsoft.com></siyanteng@loongson.cn></namjae.jeon@samsung.com>