[PATCH v2] docs: ReSTify table of contents in core.rst

[PATCH v2] docs: ReSTify table of contents in core.rst

[Josh Holland]

Sphinx will now generate the table of contents automatically, which
avoids having the ToC getting out of sync with the rest of the document.

Signed-off-by: Josh Holland <anowlcalledjosh@gmail.com>
---
 Documentation/security/keys/core.rst | 12 +-----------
 1 file changed, 1 insertion(+), 11 deletions(-)

diff --git a/Documentation/security/keys/core.rst b/Documentation/security/keys/core.rst
index 312f981fa..1266eeae4 100644
--- a/Documentation/security/keys/core.rst
+++ b/Documentation/security/keys/core.rst
@@ -16,17 +16,7 @@ The key service can be configured on by enabling:
 
 This document has the following sections:
 
-	- Key overview
-	- Key service overview
-	- Key access permissions
-	- SELinux support
-	- New procfs files
-	- Userspace system call interface
-	- Kernel services
-	- Notes on accessing payload contents
-	- Defining a key type
-	- Request-key callback service
-	- Garbage collection
+.. contents:: :local:
 
 
 Key Overview
-- 
2.14.1

Re: [PATCH v2] docs: ReSTify table of contents in core.rst

[Jani Nikula]

On Wed, 23 Aug 2017, Josh Holland <anowlcalledjosh@gmail.com> wrote:
> Sphinx will now generate the table of contents automatically, which
> avoids having the ToC getting out of sync with the rest of the document.
>
> Signed-off-by: Josh Holland <anowlcalledjosh@gmail.com>
> ---
>  Documentation/security/keys/core.rst | 12 +-----------
>  1 file changed, 1 insertion(+), 11 deletions(-)
>
> diff --git a/Documentation/security/keys/core.rst b/Documentation/security/keys/core.rst
> index 312f981fa..1266eeae4 100644
> --- a/Documentation/security/keys/core.rst
> +++ b/Documentation/security/keys/core.rst
> @@ -16,17 +16,7 @@ The key service can be configured on by enabling:
>  
>  This document has the following sections:
>  
> -	- Key overview
> -	- Key service overview
> -	- Key access permissions
> -	- SELinux support
> -	- New procfs files
> -	- Userspace system call interface
> -	- Kernel services
> -	- Notes on accessing payload contents
> -	- Defining a key type
> -	- Request-key callback service
> -	- Garbage collection
> +.. contents:: :local:

Did you actually try this and look at the 'make htmldocs' results?

I know I tried what I suggested:

.. contents::
   :local:

http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents

BR,
Jani.

>  
>  
>  Key Overview

-- 
Jani Nikula, Intel Open Source Technology Center

Re: [PATCH v2] docs: ReSTify table of contents in core.rst

[Josh Holland]

On 2017-08-24, Jani Nikula wrote:
> On Wed, 23 Aug 2017, Josh Holland <anowlcalledjosh@gmail.com> wrote:
> > Sphinx will now generate the table of contents automatically, which
> > avoids having the ToC getting out of sync with the rest of the document.
> >
> > Signed-off-by: Josh Holland <anowlcalledjosh@gmail.com>
> > ---
> >  Documentation/security/keys/core.rst | 12 +-----------
> >  1 file changed, 1 insertion(+), 11 deletions(-)
> >
> > diff --git a/Documentation/security/keys/core.rst b/Documentation/security/keys/core.rst
> > index 312f981fa..1266eeae4 100644
> > --- a/Documentation/security/keys/core.rst
> > +++ b/Documentation/security/keys/core.rst
> > @@ -16,17 +16,7 @@ The key service can be configured on by enabling:
> >  
> >  This document has the following sections:
> >  
> > -	- Key overview
> > -	- Key service overview
> > -	- Key access permissions
> > -	- SELinux support
> > -	- New procfs files
> > -	- Userspace system call interface
> > -	- Kernel services
> > -	- Notes on accessing payload contents
> > -	- Defining a key type
> > -	- Request-key callback service
> > -	- Garbage collection
> > +.. contents:: :local:
> 
> Did you actually try this and look at the 'make htmldocs' results?
> 
> I know I tried what I suggested:
> 
> .. contents::
>    :local:
> 
> http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents

Yep, I tried with sphinx_rtd_theme and it looks fine.  The documentation
suggests that the two forms are equivalent:

> If the default title is to be used, the options field list may begin
> on the same line as the directive marker:
>
>   .. contents:: :depth: 2

I went for the single-line version purely because that's what's used in
Documentation/security/credentials.rst (one of two existing users of
"contents::"), and I figured I may as well be consistent within the
security docs.  I have no particular preference either way.

Thanks,

Josh

Re: [PATCH v2] docs: ReSTify table of contents in core.rst

[Jani Nikula]

On Fri, 25 Aug 2017, Josh Holland <anowlcalledjosh@gmail.com> wrote:
> On 2017-08-24, Jani Nikula wrote:
>> On Wed, 23 Aug 2017, Josh Holland <anowlcalledjosh@gmail.com> wrote:
>> > Sphinx will now generate the table of contents automatically, which
>> > avoids having the ToC getting out of sync with the rest of the document.
>> >
>> > Signed-off-by: Josh Holland <anowlcalledjosh@gmail.com>
>> > ---
>> >  Documentation/security/keys/core.rst | 12 +-----------
>> >  1 file changed, 1 insertion(+), 11 deletions(-)
>> >
>> > diff --git a/Documentation/security/keys/core.rst b/Documentation/security/keys/core.rst
>> > index 312f981fa..1266eeae4 100644
>> > --- a/Documentation/security/keys/core.rst
>> > +++ b/Documentation/security/keys/core.rst
>> > @@ -16,17 +16,7 @@ The key service can be configured on by enabling:
>> >  
>> >  This document has the following sections:
>> >  
>> > -	- Key overview
>> > -	- Key service overview
>> > -	- Key access permissions
>> > -	- SELinux support
>> > -	- New procfs files
>> > -	- Userspace system call interface
>> > -	- Kernel services
>> > -	- Notes on accessing payload contents
>> > -	- Defining a key type
>> > -	- Request-key callback service
>> > -	- Garbage collection
>> > +.. contents:: :local:
>> 
>> Did you actually try this and look at the 'make htmldocs' results?
>> 
>> I know I tried what I suggested:
>> 
>> .. contents::
>>    :local:
>> 
>> http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents
>
> Yep, I tried with sphinx_rtd_theme and it looks fine.  The documentation
> suggests that the two forms are equivalent:
>
>> If the default title is to be used, the options field list may begin
>> on the same line as the directive marker:
>>
>>   .. contents:: :depth: 2
>
> I went for the single-line version purely because that's what's used in
> Documentation/security/credentials.rst (one of two existing users of
> "contents::"), and I figured I may as well be consistent within the
> security docs.  I have no particular preference either way.

TIL. I'm fine either way. Sorry for the noise.

BR,
Jani.


>
> Thanks,
>
> Josh
> --
> To unsubscribe from this list: send the line "unsubscribe linux-doc" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

-- 
Jani Nikula, Intel Open Source Technology Center

Re: [PATCH v2] docs: ReSTify table of contents in core.rst

[Jonathan Corbet]

On Wed, 23 Aug 2017 21:42:32 +0100
Josh Holland <anowlcalledjosh@gmail.com> wrote:

> Sphinx will now generate the table of contents automatically, which
> avoids having the ToC getting out of sync with the rest of the document.

I've (finally) applied this, thanks.

jon