Re: [PATCH v2 1/2] Documentation/sphinx: allow "functions" with no parameters

[Jani Nikula]

On Wed, 20 Jun 2018, Mike Rapoport  wrote:
> When kernel-doc:: specified in .rst document without explicit directives,
> it outputs both comment and DOC: sections. If a DOC: section was explicitly
> included in the same document it will be duplicated. For example, the
> output generated for Documentation/core-api/idr.rst [1] has "IDA
> description" in the "IDA usage" section and in the middle of the API
> reference.
>
> This patch enables using "functions" directive without parameters to output
> all the documentation excluding DOC: sections.
>
> [1] https://www.kernel.org/doc/html/v4.17/core-api/idr.html
>
> Signed-off-by: Mike Rapoport 
> Acked-by: Matthew Wilcox 

Looks good to me. Though I do realize now that I overlooked that this
applies to not only functions, but also to other non-DOC documentation
comments. I guess up to Jon to decide.

Please do give the cobbler's children some shoes, and document this in
Documentation/doc-guide/kernel-doc.rst.

Thanks,
Jani.

> ---
>  Documentation/sphinx/kerneldoc.py | 10 +++---
>  1 file changed, 7 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/sphinx/kerneldoc.py 
> b/Documentation/sphinx/kerneldoc.py
> index fbedcc3..9d0a7f0 100644
> --- a/Documentation/sphinx/kerneldoc.py
> +++ b/Documentation/sphinx/kerneldoc.py
> @@ -47,7 +47,7 @@ class KernelDocDirective(Directive):
>  optional_arguments = 4
>  option_spec = {
>  'doc': directives.unchanged_required,
> -'functions': directives.unchanged_required,
> +'functions': directives.unchanged,
>  'export': directives.unchanged,
>  'internal': directives.unchanged,
>  }
> @@ -75,8 +75,12 @@ class KernelDocDirective(Directive):
>  elif 'doc' in self.options:
>  cmd += ['-function', str(self.options.get('doc'))]
>  elif 'functions' in self.options:
> -for f in str(self.options.get('functions')).split():
> -cmd += ['-function', f]
> +functions = self.options.get('functions').split()
> +if functions:
> +for f in functions:
> +cmd += ['-function', f]
> +else:
> +cmd += ['-no-doc-sections']
>  
>  for pattern in export_file_patterns:
>  for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern):

-- 
Jani Nikula, Intel Open Source Graphics Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] Documentation/sphinx: add "nodocs" directive

[Jani Nikula]

On Tue, 19 Jun 2018, Mike Rapoport  wrote:
> On Tue, Jun 19, 2018 at 10:29:20AM +0300, Jani Nikula wrote:
>> On Tue, 19 Jun 2018, Mike Rapoport  wrote:
>> > On Mon, Jun 18, 2018 at 11:01:32PM +0300, Jani Nikula wrote:
>> >> On Mon, 18 Jun 2018, Mike Rapoport  wrote:
>> >> > When kernel-doc:: specified in .rst document without explicit 
>> >> > directives,
>> >> > it outputs both comment and DOC: sections. If a DOC: section was 
>> >> > explictly
>> >> > included in the same document it will be duplicated. For example, the
>> >> > output generated for Documentation/core-api/idr.rst [1] has "IDA
>> >> > description" in the "IDA usage" section and in the middle of the API
>> >> > reference.
>> >> >
>> >> > Addition of "nodocs" directive prevents the duplication without the 
>> >> > need to
>> >> > explicitly define what functions should be include in the API reference.
>> >> >
>> >> > [1] https://www.kernel.org/doc/html/v4.17/core-api/idr.html
>> >> >
>> >> > Signed-off-by: Mike Rapoport 
>> >> > ---
>> >> >  Documentation/sphinx/kerneldoc.py | 3 +++
>> >> >  1 file changed, 3 insertions(+)
>> >> >
>> >> > diff --git a/Documentation/sphinx/kerneldoc.py 
>> >> > b/Documentation/sphinx/kerneldoc.py
>> >> > index fbedcc3..bc5dd05 100644
>> >> > --- a/Documentation/sphinx/kerneldoc.py
>> >> > +++ b/Documentation/sphinx/kerneldoc.py
>> >> > @@ -50,6 +50,7 @@ class KernelDocDirective(Directive):
>> >> >  'functions': directives.unchanged_required,
>> >> >  'export': directives.unchanged,
>> >> >  'internal': directives.unchanged,
>> >> > +'nodocs': directives.unchanged,
>> >> 
>> >> I'm not convinved this is the prettiest way to achieve what you
>> >> want. 'nodocs' seems kind of clunky.
>> >> 
>> >> I'd suggest supporting 'functions' without option arguments, and turning
>> >> that into kernel-doc -no-doc-sections.
>> >
>> > Do you mean something like this:
>> 
>> Yes.
>> 
>> >
>> > diff --git a/Documentation/sphinx/kerneldoc.py 
>> > b/Documentation/sphinx/kerneldoc.py
>> > index fbedcc3..9d0a7f0 100644
>> > --- a/Documentation/sphinx/kerneldoc.py
>> > +++ b/Documentation/sphinx/kerneldoc.py
>> > @@ -47,7 +47,7 @@ class KernelDocDirective(Directive):
>> >  optional_arguments = 4
>> >  option_spec = {
>> >  'doc': directives.unchanged_required,
>> > -'functions': directives.unchanged_required,
>> > +'functions': directives.unchanged,
>> >  'export': directives.unchanged,
>> >  'internal': directives.unchanged,
>> >  }
>> > @@ -75,8 +75,12 @@ class KernelDocDirective(Directive):
>> >  elif 'doc' in self.options:
>> >  cmd += ['-function', str(self.options.get('doc'))]
>> >  elif 'functions' in self.options:
>> > -for f in str(self.options.get('functions')).split():
>> > -cmd += ['-function', f]
>> > +functions = self.options.get('functions').split()
>> 
>> Does .split() get upset if there's no argument? Or do you get an empty
>> string if there are no options? I forget.
>
> "".split() gives an empty list.

I tried to say, does self.options.get('functions') return an empty
string or None if there are no options?

BR,
Jani.


>  
>> BR,
>> Jani.
>> 
>> > +if functions:
>> > +for f in functions:
>> > +cmd += ['-function', f]
>> > +else:
>> > +cmd += ['-no-doc-sections']
>> >  
>> >  for pattern in export_file_patterns:
>> >      for f in glob.glob(env.config.kerneldoc_srctree + '/' + 
>> > pattern):
>> >
>> >> The usage in patch 2/2 would turn into:
>> >> 
>> >> .. kernel-doc:: include/linux/idr.h
>> >>:functions:
>> >> 
>> >> which I think is much better overall in the rst source, complementing
>> >> the places where you use :doc:.
>> >> 
>> >> BR,
>> >> Jani.
>> >> 
>> >> >  }
>> >> >  has_content = False
>> >> >  
>> >> > @@ -77,6 +78,8 @@ class KernelDocDirective(Directive):
>> >> >  elif 'functions' in self.options:
>> >> >  for f in str(self.options.get('functions')).split():
>> >> >  cmd += ['-function', f]
>> >> > +elif 'nodocs' in self.options:
>> >> > +cmd += ['-no-doc-sections']
>> >> >  
>> >> >  for pattern in export_file_patterns:
>> >> >  for f in glob.glob(env.config.kerneldoc_srctree + '/' + 
>> >> > pattern):
>> >> 
>> >> -- 
>> >> Jani Nikula, Intel Open Source Graphics Center
>> >> 
>> 
>> -- 
>> Jani Nikula, Intel Open Source Graphics Center
>> 

-- 
Jani Nikula, Intel Open Source Graphics Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] Documentation/sphinx: add "nodocs" directive

[Jani Nikula]

On Tue, 19 Jun 2018, Mike Rapoport  wrote:
> On Mon, Jun 18, 2018 at 11:01:32PM +0300, Jani Nikula wrote:
>> On Mon, 18 Jun 2018, Mike Rapoport  wrote:
>> > When kernel-doc:: specified in .rst document without explicit directives,
>> > it outputs both comment and DOC: sections. If a DOC: section was explictly
>> > included in the same document it will be duplicated. For example, the
>> > output generated for Documentation/core-api/idr.rst [1] has "IDA
>> > description" in the "IDA usage" section and in the middle of the API
>> > reference.
>> >
>> > Addition of "nodocs" directive prevents the duplication without the need to
>> > explicitly define what functions should be include in the API reference.
>> >
>> > [1] https://www.kernel.org/doc/html/v4.17/core-api/idr.html
>> >
>> > Signed-off-by: Mike Rapoport 
>> > ---
>> >  Documentation/sphinx/kerneldoc.py | 3 +++
>> >  1 file changed, 3 insertions(+)
>> >
>> > diff --git a/Documentation/sphinx/kerneldoc.py 
>> > b/Documentation/sphinx/kerneldoc.py
>> > index fbedcc3..bc5dd05 100644
>> > --- a/Documentation/sphinx/kerneldoc.py
>> > +++ b/Documentation/sphinx/kerneldoc.py
>> > @@ -50,6 +50,7 @@ class KernelDocDirective(Directive):
>> >  'functions': directives.unchanged_required,
>> >  'export': directives.unchanged,
>> >  'internal': directives.unchanged,
>> > +'nodocs': directives.unchanged,
>> 
>> I'm not convinved this is the prettiest way to achieve what you
>> want. 'nodocs' seems kind of clunky.
>> 
>> I'd suggest supporting 'functions' without option arguments, and turning
>> that into kernel-doc -no-doc-sections.
>
> Do you mean something like this:

Yes.

>
> diff --git a/Documentation/sphinx/kerneldoc.py 
> b/Documentation/sphinx/kerneldoc.py
> index fbedcc3..9d0a7f0 100644
> --- a/Documentation/sphinx/kerneldoc.py
> +++ b/Documentation/sphinx/kerneldoc.py
> @@ -47,7 +47,7 @@ class KernelDocDirective(Directive):
>  optional_arguments = 4
>  option_spec = {
>  'doc': directives.unchanged_required,
> -'functions': directives.unchanged_required,
> +'functions': directives.unchanged,
>  'export': directives.unchanged,
>  'internal': directives.unchanged,
>  }
> @@ -75,8 +75,12 @@ class KernelDocDirective(Directive):
>  elif 'doc' in self.options:
>  cmd += ['-function', str(self.options.get('doc'))]
>  elif 'functions' in self.options:
> -for f in str(self.options.get('functions')).split():
> -cmd += ['-function', f]
> +functions = self.options.get('functions').split()

Does .split() get upset if there's no argument? Or do you get an empty
string if there are no options? I forget.

BR,
Jani.

> +if functions:
> +for f in functions:
> +cmd += ['-function', f]
> +else:
> +cmd += ['-no-doc-sections']
>  
>  for pattern in export_file_patterns:
>  for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern):
>
>> The usage in patch 2/2 would turn into:
>> 
>> .. kernel-doc:: include/linux/idr.h
>>:functions:
>> 
>> which I think is much better overall in the rst source, complementing
>> the places where you use :doc:.
>> 
>> BR,
>> Jani.
>> 
>> >  }
>> >  has_content = False
>> >  
>> > @@ -77,6 +78,8 @@ class KernelDocDirective(Directive):
>> >  elif 'functions' in self.options:
>> >  for f in str(self.options.get('functions')).split():
>> >  cmd += ['-function', f]
>> > +elif 'nodocs' in self.options:
>> > +cmd += ['-no-doc-sections']
>> >  
>> >  for pattern in export_file_patterns:
>> >  for f in glob.glob(env.config.kerneldoc_srctree + '/' + 
>> > pattern):
>> 
>> -- 
>> Jani Nikula, Intel Open Source Graphics Center
>> 

-- 
Jani Nikula, Intel Open Source Graphics Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] Documentation/sphinx: add "nodocs" directive

[Jani Nikula]

On Mon, 18 Jun 2018, Mike Rapoport  wrote:
> When kernel-doc:: specified in .rst document without explicit directives,
> it outputs both comment and DOC: sections. If a DOC: section was explictly
> included in the same document it will be duplicated. For example, the
> output generated for Documentation/core-api/idr.rst [1] has "IDA
> description" in the "IDA usage" section and in the middle of the API
> reference.
>
> Addition of "nodocs" directive prevents the duplication without the need to
> explicitly define what functions should be include in the API reference.
>
> [1] https://www.kernel.org/doc/html/v4.17/core-api/idr.html
>
> Signed-off-by: Mike Rapoport 
> ---
>  Documentation/sphinx/kerneldoc.py | 3 +++
>  1 file changed, 3 insertions(+)
>
> diff --git a/Documentation/sphinx/kerneldoc.py 
> b/Documentation/sphinx/kerneldoc.py
> index fbedcc3..bc5dd05 100644
> --- a/Documentation/sphinx/kerneldoc.py
> +++ b/Documentation/sphinx/kerneldoc.py
> @@ -50,6 +50,7 @@ class KernelDocDirective(Directive):
>  'functions': directives.unchanged_required,
>  'export': directives.unchanged,
>  'internal': directives.unchanged,
> +'nodocs': directives.unchanged,

I'm not convinved this is the prettiest way to achieve what you
want. 'nodocs' seems kind of clunky.

I'd suggest supporting 'functions' without option arguments, and turning
that into kernel-doc -no-doc-sections.

The usage in patch 2/2 would turn into:

.. kernel-doc:: include/linux/idr.h
   :functions:

which I think is much better overall in the rst source, complementing
the places where you use :doc:.

BR,
Jani.

>  }
>  has_content = False
>  
> @@ -77,6 +78,8 @@ class KernelDocDirective(Directive):
>  elif 'functions' in self.options:
>  for f in str(self.options.get('functions')).split():
>  cmd += ['-function', f]
> +elif 'nodocs' in self.options:
> +cmd += ['-no-doc-sections']
>  
>  for pattern in export_file_patterns:
>  for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern):

-- 
Jani Nikula, Intel Open Source Graphics Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH 1/2] scripts/kernel-doc: Auto-detect common code-blocks

[Jani Nikula]

On Thu, 10 May 2018, Jonathan Corbet <cor...@lwn.net> wrote:
> On Thu, 10 May 2018 09:34:56 -0700
> Matthew Wilcox <wi...@infradead.org> wrote:
>
>> I think this is a bit fragile.  Why not just search for ':\n'?  Is
>> there ever a case where we want to write:
>> 
>> /**
>>  * foo is a bar:
>>  * wibble
>>  */
>> and have wibble not be a code-block?
>
> Yeah, we might want to write something like:
>
>  - Leading off a bulleted list
>
>  1) or a numbered list
>
> for example.  That's why I was thinking of looking for explicit markers
> for such lists.
>
> It'll take some playing around with to have a hope of getting right,
> methinks.

We had serious trouble with the old DocBook toolchain because the tool
pipeline was so long, and each step had its own expectations and quirks.
For example, remember the escaping needed for xml in kernel-doc? Or tmpl
xml files being invalid xml because of the docproc directives? One of
the big benefits of the current toolchain is minimizing the amount of
special casing magic required.

The more we add custom syntax sugar in kernel-doc, the more we run the
risk of running into hard problems later on in the Sphinx phase. For
example, our own syntax preventing the use of legitimate rst syntax. And
now we get somewhat reasonable error messages from Sphinx when things go
wrong; we didn't get that when the impedance mismatches caused issues
with the old toolchain. They were hard to debug and mostly nobody even
bothered. We should work to reduce the amount of special processing in
kernel-doc, not the other way round.

The use of "::" is a valid and arguably rather non-invasive rst token
for indicating the following indented block is a literal block. Adding
heuristics (especially ones based on English language magic words) will
lead to bigger problems than it's trying to solve.


BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 05/18] docs: core-api: add cachetlb documentation

[Jani Nikula]

On Mon, 07 May 2018, Andrea Parri <andrea.pa...@amarulasolutions.com> wrote:
> On Mon, May 07, 2018 at 06:35:41AM -0300, Mauro Carvalho Chehab wrote:
>> The cachetlb.txt is already in ReST format. So, move it to the
>> core-api guide, where it belongs.
>> 
>> Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>
>> ---
>>  Documentation/00-INDEX| 2 --
>>  Documentation/{cachetlb.txt => core-api/cachetlb.rst} | 0
>>  Documentation/core-api/index.rst  | 1 +
>>  Documentation/memory-barriers.txt | 2 +-
>>  Documentation/translations/ko_KR/memory-barriers.txt  | 2 +-
>>  5 files changed, 3 insertions(+), 4 deletions(-)
>>  rename Documentation/{cachetlb.txt => core-api/cachetlb.rst} (100%)
>
> I see a few "inline" references to the .txt file in -rc4 (see below):
> I am not sure if you managed to update them too.

Side note, there's scripts/documentation-file-ref-check to grep the
kernel tree for things that look like file references to Documentation/*
and complain if they don't exist.

I get about 350+ hits with that, patches welcome! ;)


BR,
Jani.


>
> ./arch/microblaze/include/asm/cacheflush.h:/* Look at 
> Documentation/cachetlb.txt */
> ./arch/unicore32/include/asm/cacheflush.h: *  See Documentation/cachetlb.txt 
> for more information.
> ./arch/arm64/include/asm/cacheflush.h: *  See Documentation/cachetlb.txt 
> for more information. Please note that
> ./arch/arm/include/asm/cacheflush.h: *See Documentation/cachetlb.txt 
> for more information.
> ./arch/xtensa/include/asm/cacheflush.h: * (see also 
> Documentation/cachetlb.txt)
> ./arch/xtensa/include/asm/cacheflush.h:/* This is not required, see 
> Documentation/cachetlb.txt */
>
>   Andrea
>
>
>> 
>> diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
>> index 53699c79ee54..04074059bcdc 100644
>> --- a/Documentation/00-INDEX
>> +++ b/Documentation/00-INDEX
>> @@ -76,8 +76,6 @@ bus-devices/
>>  - directory with info on TI GPMC (General Purpose Memory Controller)
>>  bus-virt-phys-mapping.txt
>>  - how to access I/O mapped memory from within device drivers.
>> -cachetlb.txt
>> -- describes the cache/TLB flushing interfaces Linux uses.
>>  cdrom/
>>  - directory with information on the CD-ROM drivers that Linux has.
>>  cgroup-v1/
>> diff --git a/Documentation/cachetlb.txt b/Documentation/core-api/cachetlb.rst
>> similarity index 100%
>> rename from Documentation/cachetlb.txt
>> rename to Documentation/core-api/cachetlb.rst
>> diff --git a/Documentation/core-api/index.rst 
>> b/Documentation/core-api/index.rst
>> index c670a8031786..d4d71ee564ae 100644
>> --- a/Documentation/core-api/index.rst
>> +++ b/Documentation/core-api/index.rst
>> @@ -14,6 +14,7 @@ Core utilities
>> kernel-api
>> assoc_array
>> atomic_ops
>> +   cachetlb
>> refcount-vs-atomic
>> cpu_hotplug
>> idr
>> diff --git a/Documentation/memory-barriers.txt 
>> b/Documentation/memory-barriers.txt
>> index 6dafc8085acc..983249906fc6 100644
>> --- a/Documentation/memory-barriers.txt
>> +++ b/Documentation/memory-barriers.txt
>> @@ -2903,7 +2903,7 @@ is discarded from the CPU's cache and reloaded.  To 
>> deal with this, the
>>  appropriate part of the kernel must invalidate the overlapping bits of the
>>  cache on each CPU.
>>  
>> -See Documentation/cachetlb.txt for more information on cache management.
>> +See Documentation/core-api/cachetlb.rst for more information on cache 
>> management.
>>  
>>  
>>  CACHE COHERENCY VS MMIO
>> diff --git a/Documentation/translations/ko_KR/memory-barriers.txt 
>> b/Documentation/translations/ko_KR/memory-barriers.txt
>> index 0a0930ab4156..081937577c1a 100644
>> --- a/Documentation/translations/ko_KR/memory-barriers.txt
>> +++ b/Documentation/translations/ko_KR/memory-barriers.txt
>> @@ -2846,7 +2846,7 @@ CPU 의 캐시에서 RAM 으로 쓰여지는 더티 캐시 라인에 의해 덮
>>  문제를 해결하기 위해선, 커널의 적절한 부분에서 각 CPU 의 캐시 안의 문제가 되는
>>  비트들을 무효화 시켜야 합니다.
>>  
>> -캐시 관리에 대한 더 많은 정보를 위해선 Documentation/cachetlb.txt 를
>> +캐시 관리에 대한 더 많은 정보를 위해선 Documentation/core-api/cachetlb.rst 를
>>  참고하세요.
>>  
>>  
>> -- 
>> 2.17.0
>> 
> --
> To unsubscribe from this list: send the line "unsubscribe linux-doc" in
> the body of a message to majord...@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] MAINTAINERS & files: Canonize the e-mails I use at files

[Jani Nikula]

On Fri, 04 May 2018, Mauro Carvalho Chehab <mchehab+sams...@kernel.org> wrote:
> From now on, I'll start using my @kernel.org as my development e-mail.
>
> As such, let's remove the entries that point to the old
> mche...@s-opensource.com at MAINTAINERS file.
>
> For the files written with a copyright with mchehab@s-opensource,
> let's keep Samsung on their names, using mchehab+sams...@kernel.org,
> in order to keep pointing to my employer, with sponsors the work.
>
> For the files written before I join Samsung (on July, 4 2013),
> let's just use mche...@kernel.org.
>
> For bug reports, we can simply point to just kernel.org, as
> this will reach my mchehab+samsung inbox anyway.

I suppose this begs the question, why do we insist on adding our email
addresses all over the place? On a quick grep, there are at least 40k+
email addresses in the sources. Do we expect them all to be up-to-date
too?


BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] Documentation: typec.rst: Use literal-block element with ascii art

[Jani Nikula]

On Fri, 06 Apr 2018, Heikki Krogerus <heikki.kroge...@linux.intel.com> wrote:
> Using reStructuredText literal-block element with ascii-art.
> That prevents the ascii art from being processed as
> reStructuredText.
>
> Reported-by: Masanari Iida <standby2...@gmail.com>
> Fixes: bdecb33af34f ("usb: typec: API for controlling USB Type-C 
> Multiplexers")
> Signed-off-by: Heikki Krogerus <heikki.kroge...@linux.intel.com>

Jon, this fixes a documentation build failure in v4.17-rc1. It's not
just a warning, it's a complete fail. Our docs builder at 01.org is
failing, apparently the same at kernel.org. Please pick it up soon.

Thanks,
Jani.

> ---
> Changed since v1:
> - Using literal-block element instead of comment
> - Subject in v1 was "Documentation: typec.rst: Mark ascii art as a comment"
> ---
>  Documentation/driver-api/usb/typec.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/driver-api/usb/typec.rst 
> b/Documentation/driver-api/usb/typec.rst
> index feb31946490b..48ff58095f11 100644
> --- a/Documentation/driver-api/usb/typec.rst
> +++ b/Documentation/driver-api/usb/typec.rst
> @@ -210,7 +210,7 @@ If the connector is dual-role capable, there may also be 
> a switch for the data
>  role. USB Type-C Connector Class does not supply separate API for them. The
>  port drivers can use USB Role Class API with those.
>  
> -Illustration of the muxes behind a connector that supports an alternate mode:
> +Illustration of the muxes behind a connector that supports an alternate 
> mode::
>  
>   
>   |   Connector  |

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] Documentation: typec.rst: Use literal-block element with ascii art

[Jani Nikula]

On Fri, 06 Apr 2018, Heikki Krogerus <heikki.kroge...@linux.intel.com> wrote:
> Using reStructuredText literal-block element with ascii-art.
> That prevents the ascii art from being processed as
> reStructuredText.
>
> Reported-by: Masanari Iida <standby2...@gmail.com>
> Fixes: bdecb33af34f ("usb: typec: API for controlling USB Type-C 
> Multiplexers")
> Signed-off-by: Heikki Krogerus <heikki.kroge...@linux.intel.com>

Reviewed-and-tested-by: Jani Nikula <jani.nik...@intel.com>


> ---
> Changed since v1:
> - Using literal-block element instead of comment
> - Subject in v1 was "Documentation: typec.rst: Mark ascii art as a comment"
> ---
>  Documentation/driver-api/usb/typec.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/driver-api/usb/typec.rst 
> b/Documentation/driver-api/usb/typec.rst
> index feb31946490b..48ff58095f11 100644
> --- a/Documentation/driver-api/usb/typec.rst
> +++ b/Documentation/driver-api/usb/typec.rst
> @@ -210,7 +210,7 @@ If the connector is dual-role capable, there may also be 
> a switch for the data
>  role. USB Type-C Connector Class does not supply separate API for them. The
>  port drivers can use USB Role Class API with those.
>  
> -Illustration of the muxes behind a connector that supports an alternate mode:
> +Illustration of the muxes behind a connector that supports an alternate 
> mode::
>  
>   
>   |   Connector  |

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation: typec.rst: Mark ascii art as a comment

[Jani Nikula]

On Fri, 06 Apr 2018, Heikki Krogerus <heikki.kroge...@linux.intel.com> wrote:
> To prevent processing of ascii art as reStructuredText
> elements, marking it as a comment.

Please don't. This hides the ascii art from the generated documentation.

The right fix is to use a reStructuredText literal block like this:

diff --git a/Documentation/driver-api/usb/typec.rst 
b/Documentation/driver-api/usb/typec.rst
index feb31946490b..48ff58095f11 100644
--- a/Documentation/driver-api/usb/typec.rst
+++ b/Documentation/driver-api/usb/typec.rst
@@ -210,7 +210,7 @@ If the connector is dual-role capable, there may also be a 
switch for the data
 role. USB Type-C Connector Class does not supply separate API for them. The
 port drivers can use USB Role Class API with those.
 
-Illustration of the muxes behind a connector that supports an alternate mode:
+Illustration of the muxes behind a connector that supports an alternate mode::
 
  
  |   Connector  |


BR,
Jani.


>
> Reported-by: Masanari Iida <standby2...@gmail.com>
> Fixes: bdecb33af34f ("usb: typec: API for controlling USB Type-C 
> Multiplexers")
> Signed-off-by: Heikki Krogerus <heikki.kroge...@linux.intel.com>
> ---
>  Documentation/driver-api/usb/typec.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/driver-api/usb/typec.rst 
> b/Documentation/driver-api/usb/typec.rst
> index feb31946490b..972c11bf4141 100644
> --- a/Documentation/driver-api/usb/typec.rst
> +++ b/Documentation/driver-api/usb/typec.rst
> @@ -212,7 +212,7 @@ port drivers can use USB Role Class API with those.
>  
>  Illustration of the muxes behind a connector that supports an alternate mode:
>  
> - 
> +..   
>   |   Connector  |
>   
>  | |

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] Documentation/CodingStyle: Add an example for braces

[Jani Nikula]

On Wed, 21 Mar 2018, Jonathan Corbet <cor...@lwn.net> wrote:
> To head that off, I think I'll apply your first version instead, sorry
> Jani.

No worries.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation/CodingStyle: Add an example for braces

[Jani Nikula]

On Wed, 14 Mar 2018, Gary R Hook <gary.h...@amd.com> wrote:
> Add another example of required braces when using a compound statement in
> a loop.
>
> Signed-off-by: Gary R Hook <gary.h...@amd.com>
> ---
>  Documentation/process/coding-style.rst |9 +
>  1 file changed, 9 insertions(+)
>
> diff --git a/Documentation/process/coding-style.rst 
> b/Documentation/process/coding-style.rst
> index a20b44a40ec4..d98deb62c400 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -200,6 +200,15 @@ statement; in the latter case use braces in both 
> branches:
>   otherwise();
>   }
>  
> +Also, use braces when a loop contains more than a single simple statement:

Personally, I'd not limit this to loops.

if (condition) {
if (another_condition)
action();
}

You could argue the existing rule already covers these cases by
excluding selection and iteration statements from the "single statement"
in "Do not unnecessarily use braces where a single statement will do."

BR,
Jani.

> +
> +.. code-block:: c
> +
> + while (condition) {
> + if (test)
> + do_something();
> + }
> +
>  3.1) Spaces
>  ***
>  
>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-doc" in
> the body of a message to majord...@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3] Documentation/sphinx: Fix Directive import error

[Jani Nikula]

On Fri, 02 Mar 2018, Matthew Wilcox <wi...@infradead.org> wrote:
> From: Matthew Wilcox <mawil...@microsoft.com>
>
> Sphinx 1.7 removed sphinx.util.compat.Directive so people
> who have upgraded cannot build the documentation.  Switch to
> docutils.parsers.rst.Directive which has been available since
> docutils 0.5 released in 2009.
>
> Bugzilla: https://bugzilla.opensuse.org/show_bug.cgi?id=1083694
> Co-developed-by: Takashi Iwai <ti...@suse.de>
> Signed-off-by: Matthew Wilcox <mawil...@microsoft.com>

I think this is the best approach.

FWIW,

Acked-by: Jani Nikula <jani.nik...@intel.com>

>
> diff --git a/Documentation/sphinx/kerneldoc.py 
> b/Documentation/sphinx/kerneldoc.py
> index 39aa9e8697cc..fbedcc39460b 100644
> --- a/Documentation/sphinx/kerneldoc.py
> +++ b/Documentation/sphinx/kerneldoc.py
> @@ -36,8 +36,7 @@ import glob
>  
>  from docutils import nodes, statemachine
>  from docutils.statemachine import ViewList
> -from docutils.parsers.rst import directives
> -from sphinx.util.compat import Directive
> +from docutils.parsers.rst import directives, Directive
>  from sphinx.ext.autodoc import AutodocReporter
>  
>  __version__  = '1.0'

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] Documentation/sphinx: Fix Directive import error

[Jani Nikula]

On Fri, 02 Mar 2018, Takashi Iwai <ti...@suse.de> wrote:
> The sphinx.util.compat for Directive stuff was deprecated in the
> recent Sphinx version, and now we get a build error.
>
> Let's import from the new place, docutils.parsers.rst, while keeping
> the old sphinx.util.compat as fallback.
>
> Bugzilla: https://bugzilla.opensuse.org/show_bug.cgi?id=1083694
> Signed-off-by: Takashi Iwai <ti...@suse.de>
> ---
> v1->v2: Change the fallback order as Matthew suggested, the new one at first

So this crossed my mind as well... and then I thought it'll probably
succeed on older Sphinx, and the fallback is not needed. The question
is, are these equal? Can we just import from docutils.parsers.rst?

I'm sorry I don't have the time to find the answers to these questions
as well. :(

BR,
Jani.


>
>  Documentation/sphinx/kerneldoc.py | 5 -
>  1 file changed, 4 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/sphinx/kerneldoc.py 
> b/Documentation/sphinx/kerneldoc.py
> index 39aa9e8697cc..34396976eb0a 100644
> --- a/Documentation/sphinx/kerneldoc.py
> +++ b/Documentation/sphinx/kerneldoc.py
> @@ -37,7 +37,10 @@ import glob
>  from docutils import nodes, statemachine
>  from docutils.statemachine import ViewList
>  from docutils.parsers.rst import directives
> -from sphinx.util.compat import Directive
> +try:
> +from docutils.parsers.rst import directives, Directive
> +except ImportError:
> +from sphinx.util.compat import Directive
>  from sphinx.ext.autodoc import AutodocReporter
>  
>  __version__  = '1.0'

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 05/10] pwm: add PWM mode to pwm_config()

[Jani Nikula]

On Thu, 22 Feb 2018, Daniel Thompson <daniel.thomp...@linaro.org> wrote:
> On Thu, Feb 22, 2018 at 02:01:16PM +0200, Claudiu Beznea wrote:
>> Add PWM mode to pwm_config() function. The drivers which uses pwm_config()
>> were adapted to this change.
>> 
>> Signed-off-by: Claudiu Beznea <claudiu.bez...@microchip.com>
>> ---
>>  arch/arm/mach-s3c24xx/mach-rx1950.c  | 11 +--
>>  drivers/bus/ts-nbus.c|  2 +-
>>  drivers/clk/clk-pwm.c|  3 ++-
>>  drivers/gpu/drm/i915/intel_panel.c   | 17 ++---
>>  drivers/hwmon/pwm-fan.c  |  2 +-
>>  drivers/input/misc/max77693-haptic.c |  2 +-
>>  drivers/input/misc/max8997_haptic.c  |  6 +-
>>  drivers/leds/leds-pwm.c  |  5 -
>>  drivers/media/rc/ir-rx51.c   |  5 -
>>  drivers/media/rc/pwm-ir-tx.c |  5 -
>>  drivers/video/backlight/lm3630a_bl.c |  4 +++-
>>  drivers/video/backlight/lp855x_bl.c  |  4 +++-
>>  drivers/video/backlight/lp8788_bl.c  |  5 -
>>  drivers/video/backlight/pwm_bl.c | 11 +--
>>  drivers/video/fbdev/ssd1307fb.c  |  3 ++-
>>  include/linux/pwm.h  |  6 --
>>  16 files changed, 70 insertions(+), 21 deletions(-)
>> 
>> diff --git a/drivers/video/backlight/lm3630a_bl.c 
>> b/drivers/video/backlight/lm3630a_bl.c
>> index 2030a6b77a09..696fa25dafd2 100644
>> --- a/drivers/video/backlight/lm3630a_bl.c
>> +++ b/drivers/video/backlight/lm3630a_bl.c
>> @@ -165,8 +165,10 @@ static void lm3630a_pwm_ctrl(struct lm3630a_chip 
>> *pchip, int br, int br_max)
>>  {
>>  unsigned int period = pchip->pdata->pwm_period;
>>  unsigned int duty = br * period / br_max;
>> +struct pwm_caps caps = { };
>>  
>> -pwm_config(pchip->pwmd, duty, period);
>> +pwm_get_caps(pchip->pwmd->chip, pchip->pwmd, );
>> +pwm_config(pchip->pwmd, duty, period, BIT(ffs(caps.modes) - 1));
>
> Well... I admit I've only really looked at the patches that impact 
> backlight but dispersing this really odd looking bit twiddling 
> throughout the kernel doesn't strike me a great API design.
>
> IMHO callers should not be required to find the first set bit in
> some specially crafted set of capability bits simply to get sane 
> default behaviour.

Agreed. IMHO the regular use case becomes rather tedious, ugly, and
error prone.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/6] Add support for in-line nested struct comments

[Jani Nikula]

On Sun, 18 Feb 2018, Jonathan Corbet <cor...@lwn.net> wrote:
> On Fri, 16 Feb 2018 11:48:14 -0200
> Mauro Carvalho Chehab <mche...@s-opensource.com> wrote:
>
>> his series fix two bugs at kernel-doc.rst examples and add support
>> for in-line nested struct comments.
>> 
>> It also converts one documentation at intel_dpio_phy to use it,
>> in order to give a practical example about how to use it.
>
> OK, I've applied everything but the last patch, which I assume will go
> through the DRM tree.

I was going to reference the kernel-doc commit while applying patch 6,
but I can't find the others. I guess applied literally meant just
applied, not pushed... ;)

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 8/8] docs: kernel-doc: Don't mangle literal code blocks in comments

[Jani Nikula]

On Wed, 14 Feb 2018, Jonathan Corbet <cor...@lwn.net> wrote:
> It can be useful to put code snippets into kerneldoc comments; that can be
> done with the "::" operator at the end of a line like this::
>
>if (desperate)
>run_in_circles();
>
> The ".. code-block::" directive can also be used to this end.  kernel-doc
> currently fails to understand these literal blocks and applies its normal
> markup to them, which is then treated as literal by sphinx.  The result is
> unsightly markup instead of a useful code snippet.
>
> Apply a hack to the output code to recognize literal blocks and avoid
> performing any special markup on them.  It's ugly, but that means it fits
> in well with the rest of the script.

With emphasis on part (d) of the reviewer's statement of oversight,

Reviewed-by: Jani Nikula <jani.nik...@intel.com>

>
> Signed-off-by: Jonathan Corbet <cor...@lwn.net>
> ---
>  scripts/kernel-doc | 69 
> ++
>  1 file changed, 64 insertions(+), 5 deletions(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index fb8fbdb25036..cbe864e72a2f 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -748,14 +748,73 @@ sub output_blockhead_rst(%) {
>  }
>  }
>  
> -sub output_highlight_rst {
> -my $contents = join "\n",@_;
> -my $line;
> -
> +#
> +# Apply the RST highlights to a sub-block of text.
> +#   
> +sub highlight_block($) {
> +# The dohighlight kludge requires the text be called $contents
> +my $contents = shift;
>  eval $dohighlight;
>  die $@ if $@;
> +return $contents;
> +}
>  
> -foreach $line (split "\n", $contents) {
> +#
> +# Regexes used only here.
> +#
> +my $sphinx_literal = '^[^.].*::$';
> +my $sphinx_cblock = '^\.\.\ +code-block::';
> +
> +sub output_highlight_rst {
> +my $input = join "\n",@_;
> +my $output = "";
> +my $line;
> +my $in_literal = 0;
> +my $litprefix;
> +my $block = "";
> +
> +foreach $line (split "\n",$input) {
> + #
> + # If we're in a literal block, see if we should drop out
> + # of it.  Otherwise pass the line straight through unmunged.
> + #
> + if ($in_literal) {
> + if (! ($line =~ /^\s*$/)) {
> + #
> + # If this is the first non-blank line in a literal
> + # block we need to figure out what the proper indent is.
> + #
> + if ($litprefix eq "") {
> + $line =~ /^(\s*)/;
> + $litprefix = '^' . $1;
> + $output .= $line . "\n";
> + } elsif (! ($line =~ /$litprefix/)) {
> + $in_literal = 0;
> + } else {
> + $output .= $line . "\n";
> + }
> + } else {
> + $output .= $line . "\n";
> + }
> + }
> + #
> + # Not in a literal block (or just dropped out)
> + #
> + if (! $in_literal) {
> + $block .= $line . "\n";
> + if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
> + $in_literal = 1;
> + $litprefix = "";
> + $output .= highlight_block($block);
> + $block = ""
> + }
> + }
> +}
> +
> +if ($block) {
> + $output .= highlight_block($block);
> +}
> +foreach $line (split "\n", $output) {
>   print $lineprefix . $line . "\n";
>  }
>  }

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/8] docs: kernel-doc: Get rid of xml_escape() and friends

[Jani Nikula]

On Wed, 14 Feb 2018, Jonathan Corbet <cor...@lwn.net> wrote:
> XML escaping is a worry that came with DocBook, which we no longer have any
> dealings with.  So get rid of the useless xml_escape()/xml_unescape()
> functions.  No change to the generated output.
>
> Signed-off-by: Jonathan Corbet <cor...@lwn.net>

Reviewed-by: Jani Nikula <jani.nik...@intel.com>

> ---
>  scripts/kernel-doc | 65 
> --
>  1 file changed, 9 insertions(+), 56 deletions(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index fee8952037b1..5aa4ce211fc6 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -553,10 +553,9 @@ sub output_highlight {
>   }
>   if ($line eq ""){
>   if (! $output_preformatted) {
> - print $lineprefix, local_unescape($blankline);
> + print $lineprefix, $blankline;
>   }
>   } else {
> - $line =~ s/\\/\&/g;
>   if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
>   print "\\&$line";
>   } else {
> @@ -751,9 +750,6 @@ sub output_highlight_rst {
>  my $contents = join "\n",@_;
>  my $line;
>  
> -# undo the evil effects of xml_escape() earlier
> -$contents = xml_unescape($contents);
> -
>  eval $dohighlight;
>  die $@ if $@;
>  
> @@ -1422,8 +1418,6 @@ sub push_parameter() {
>   }
>   }
>  
> - $param = xml_escape($param);
> -
>   # strip spaces from $param so that it is one continuous string
>   # on @parameterlist;
>   # this fixes a problem where check_sections() cannot find
> @@ -1748,47 +1742,6 @@ sub process_proto_type($$) {
>  }
>  }
>  
> -# xml_escape: replace <, >, and & in the text stream;
> -#
> -# however, formatting controls that are generated internally/locally in the
> -# kernel-doc script are not escaped here; instead, they begin life like
> -# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
> -# are converted to their mnemonic-expected output, without the 4 * '\' & ':',
> -# just before actual output; (this is done by local_unescape())
> -sub xml_escape($) {
> - my $text = shift;
> - if ($output_mode eq "man") {
> - return $text;
> - }
> - $text =~ s/\&/\\amp;/g;
> - $text =~ s/\ - $text =~ s/\>/\\gt;/g;
> - return $text;
> -}
> -
> -# xml_unescape: reverse the effects of xml_escape
> -sub xml_unescape($) {
> - my $text = shift;
> - if ($output_mode eq "man") {
> - return $text;
> - }
> - $text =~ s/\\amp;/\&/g;
> - $text =~ s/\\lt;/ - $text =~ s/\\gt;/>/g;
> - return $text;
> -}
> -
> -# convert local escape strings to html
> -# local escape strings look like:  'menmonic:' (that's 4 backslashes)
> -sub local_unescape($) {
> - my $text = shift;
> - if ($output_mode eq "man") {
> - return $text;
> - }
> - $text =~ s/lt:/ - $text =~ s/gt:/>/g;
> - return $text;
> -}
>  
>  sub map_filename($) {
>  my $file;
> @@ -1889,7 +1842,7 @@ sub process_file($) {
>   $descr =~ s/^\s*//;
>   $descr =~ s/\s*$//;
>   $descr =~ s/\s+/ /g;
> - $declaration_purpose = xml_escape($descr);
> + $declaration_purpose = $descr;
>   $in_purpose = 1;
>   } else {
>   $declaration_purpose = "";
> @@ -1944,7 +1897,7 @@ sub process_file($) {
>   print STDERR "${file}:$.: warning: contents before 
> sections\n";
>   ++$warnings;
>   }
> - dump_section($file, $section, xml_escape($contents));
> + dump_section($file, $section, $contents);
>   $section = $section_default;
>   }
>  
> @@ -1962,7 +1915,7 @@ sub process_file($) {
>   $leading_space = undef;
>   } elsif (/$doc_end/) {
>   if (($contents ne "") && ($contents ne "\n")) {
> - dump_section($file, $section, xml_escape($contents));
> + dump_section($file, $section, $contents);
>   $section = $section_default;
>   $contents = "";
>   }
> @@ -1981,7 +1934,7 @@ sub process_file($) {
>   # @parameter line to signify start of description

Re: [PATCH v4 16/18] scripts: kernel-doc: improve nested logic to handle multiple identifiers

[Jani Nikula]

On Wed, 14 Feb 2018, Mauro Carvalho Chehab <mche...@s-opensource.com> wrote:
> There is a simple fix, though. Make inline comments to accept a dot:
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index fee8952037b1..06d7f3f2c094 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -363,7 +363,7 @@ my $doc_sect = $doc_com .
>  my $doc_content = $doc_com_body . '(.*)';
>  my $doc_block = $doc_com . 'DOC:\s*(.*)?';
>  my $doc_inline_start = '^\s*/\*\*\s*$';
> -my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
> +my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
>  my $doc_inline_end = '^\s*\*/\s*$';
>  my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
>  my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
>
> That requires a small change at the inline parameters, though:
>
> diff --git a/drivers/gpu/drm/i915/intel_dpio_phy.c 
> b/drivers/gpu/drm/i915/intel_dpio_phy.c
> index 76473e9836c6..c8e9e44e5981 100644
> --- a/drivers/gpu/drm/i915/intel_dpio_phy.c
> +++ b/drivers/gpu/drm/i915/intel_dpio_phy.c
> @@ -147,7 +147,7 @@ struct bxt_ddi_phy_info {
>*/
>   struct {
>   /**
> -  * @port: which port maps to this channel.
> +  * @channel.port: which port maps to this channel.
>*/
>   enum port port;
>   } channel[2];

Perhaps it would be slightly more elegant to be able to leave out
"channel." here and deduce that from the context... but the above
matches what you'd write in the higher level struct comment, and
produces the same output. It works and it's really simple. I like it.

Please submit this as a proper patch, with

Tested-by: Jani Nikula <jani.nik...@intel.com>

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v4 16/18] scripts: kernel-doc: improve nested logic to handle multiple identifiers

[Jani Nikula]

 next;
> + }
> + foreach my $name (split /,/, $names) {
> + $name =~ s/^\s*\**(\S+)\s*/$1/;
> + next if (($name =~ m/^\s*$/));
> + if ($id =~ m/^\s*$/) {
> + # anonymous struct/union
> + $newmember .= "$type 
> $name; ";
> + } else {
> + $newmember .= "$type 
> $id.$name; ";
> + }
>   }
>   }
>   }
> - $members =~ 
> s/(struct|union)([^{};]+){([^{}]*)}([^{}\;]*)\;/$newmember/;
> - $cont = 1;
> - };
> - };
> + }
> + $members =~ 
> s/(struct|union)([^\{\};]+)\{([^\{\}]*)}([^\{\}\;]*)\;/$newmember/;
> + }
>  
>   # Ignore other nested elements, like enums
>   $members =~ s/({[^\{\}]*})//g;

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 5/8] docs: kernel-doc: Move STATE_BODY processing to a separate function

[Jani Nikula]

On Fri, 09 Feb 2018, Linus Torvalds <torva...@linux-foundation.org> wrote:
> On Fri, Feb 9, 2018 at 1:32 AM, Jani Nikula <jani.nik...@linux.intel.com> 
> wrote:
>>> + # miguel-style comment kludge, look for blank lines after
>>> + # @parameter line to signify start of description
>>
>> The "miguel-style" always intrigued me, but its origin predates git
>> history. Does anyone know?
>
> It came with the original script in 2.3.52-pre1, somewhere around March 2000.
>
> (Historical footnote: there was no actual 2.3.52 ever released - it
> was supposed turn into 2.4, but there was a long line of 2.3.99-pre
> kernels before that then finally happened early 2001).
>
> But no, back then we didn't track things well enough to have an actual
> reason. And even with git, we probably wouldn't have had a reason
> since it came in the initial patch.
>
> You'd have to go search emails if you really care. That "around March
> 2000" would at least give you a starting point for searches.

Thanks for the background digging! I had a cursory look at the list
archives, nothing much jumped at me but I found that the script was
originally called gdoc. A little googling revealed that other forks of
the script predating inclusion to the kernel also included the comment.

I'll bet whoever added that didn't think someone would wonder about it
two decades later.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 6/8] docs: kernel-doc: Move STATE_PROTO processing into its own function

[Jani Nikula]

On Wed, 07 Feb 2018, Jonathan Corbet <cor...@lwn.net> wrote:
> Move the top-level prototype-processing code out of process_file().
>
> Signed-off-by: Jonathan Corbet <cor...@lwn.net>

Reviewed-by: Jani Nikula <jani.nik...@intel.com>

> ---
>  scripts/kernel-doc | 46 --
>  1 file changed, 28 insertions(+), 18 deletions(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index a6a7bb46ea29..2deddb876156 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1965,6 +1965,32 @@ sub process_body($$) {
>  }
>  
>  
> +#
> +# STATE_PROTO: reading a function/whatever prototype.
> +#
> +sub process_proto($$) {
> +my $file = shift;
> +
> +if (/$doc_inline_oneline/) {
> + $section = $1;
> + $contents = $2;
> + if ($contents ne "") {
> + $contents .= "\n";
> + dump_section($file, $section, $contents);
> + $section = $section_default;
> + $contents = "";
> + }
> +} elsif (/$doc_inline_start/) {
> + $state = STATE_INLINE;
> + $inline_doc_state = STATE_INLINE_NAME;
> +} elsif ($decl_type eq 'function') {
> + process_proto_function($_, $file);
> +} else {
> + process_proto_type($_, $file);
> +}
> +}
> +
> +
>  sub process_file($) {
>  my $file;
>  my $func;
> @@ -2031,24 +2057,8 @@ sub process_file($) {
>   ++$warnings;
>   }
>   }
> - } elsif ($state == STATE_PROTO) {   # scanning for function '{' 
> (end of prototype)
> - if (/$doc_inline_oneline/) {
> - $section = $1;
> - $contents = $2;
> - if ($contents ne "") {
> - $contents .= "\n";
> - dump_section($file, $section, $contents);
> - $section = $section_default;
> - $contents = "";
> - }
> - } elsif (/$doc_inline_start/) {
> - $state = STATE_INLINE;
> - $inline_doc_state = STATE_INLINE_NAME;
> - } elsif ($decl_type eq 'function') {
> - process_proto_function($_, $file);
> - } else {
> - process_proto_type($_, $file);
> - }
> + } elsif ($state == STATE_PROTO) {
> + process_proto($file, $_);
>   } elsif ($state == STATE_DOCBLOCK) {
>   if (/$doc_end/)
>   {

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 5/8] docs: kernel-doc: Move STATE_BODY processing to a separate function

[Jani Nikula]

On Wed, 07 Feb 2018, Jonathan Corbet <cor...@lwn.net> wrote:
> Also group the pseudo-global $leading_space variable with its peers.
>
> Signed-off-by: Jonathan Corbet <cor...@lwn.net>
> ---
>  scripts/kernel-doc | 193 
> -
>  1 file changed, 101 insertions(+), 92 deletions(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index a27c7016f72d..a6a7bb46ea29 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -336,6 +336,7 @@ use constant {
>  };
>  my $state;
>  my $in_doc_sect;
> +my $leading_space;
>  
>  # Inline documentation state
>  use constant {
> @@ -1865,12 +1866,110 @@ sub process_name($$) {
>  }
>  }
>  
> +
> +#
> +# STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
> +#
> +sub process_body($$) {
> +my $file = shift;
> +
> +if (/$doc_sect/i) { # case insensitive for supported section names
> + $newsection = $1;
> + $newcontents = $2;
> +
> + # map the supported section names to the canonical names
> + if ($newsection =~ m/^description$/i) {
> + $newsection = $section_default;
> + } elsif ($newsection =~ m/^context$/i) {
> + $newsection = $section_context;
> + } elsif ($newsection =~ m/^returns?$/i) {
> + $newsection = $section_return;
> + } elsif ($newsection =~ m/^\@return$/) {
> + # special: @return is a section, not a param description
> + $newsection = $section_return;
> + }
> +
> + if (($contents ne "") && ($contents ne "\n")) {
> + if (!$in_doc_sect && $verbose) {
> + print STDERR "${file}:$.: warning: contents before sections\n";
> + ++$warnings;
> + }
> + dump_section($file, $section, $contents);
> + $section = $section_default;
> + }
> +
> + $in_doc_sect = 1;
> + $state = STATE_BODY;
> + $contents = $newcontents;
> + $new_start_line = $.;
> + while (substr($contents, 0, 1) eq " ") {
> + $contents = substr($contents, 1);
> + }
> + if ($contents ne "") {
> + $contents .= "\n";
> + }
> + $section = $newsection;
> + $leading_space = undef;
> +} elsif (/$doc_end/) {
> + if (($contents ne "") && ($contents ne "\n")) {
> + dump_section($file, $section, $contents);
> + $section = $section_default;
> + $contents = "";
> + }
> + # look for doc_com +  + doc_end:
> + if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
> + print STDERR "${file}:$.: warning: suspicious ending line: $_";
> + ++$warnings;
> + }
> +
> + $prototype = "";
> + $state = STATE_PROTO;
> + $brcount = 0;
> +} elsif (/$doc_content/) {
> + # miguel-style comment kludge, look for blank lines after
> + # @parameter line to signify start of description

The "miguel-style" always intrigued me, but its origin predates git
history. Does anyone know?

Reviewed-by: Jani Nikula <jani.nik...@intel.com>

> + if ($1 eq "") {
> + if ($section =~ m/^@/ || $section eq $section_context) {
> + dump_section($file, $section, $contents);
> + $section = $section_default;
> + $contents = "";
> + $new_start_line = $.;
> + } else {
> + $contents .= "\n";
> + }
> + $state = STATE_BODY;
> + } elsif ($state == STATE_BODY_MAYBE) {
> + # Continued declaration purpose
> + chomp($declaration_purpose);
> + $declaration_purpose .= " " . $1;
> + $declaration_purpose =~ s/\s+/ /g;
> + } else {
> + my $cont = $1;
> + if ($section =~ m/^@/ || $section eq $section_context) {
> + if (!defined $leading_space) {
> + if ($cont =~ m/^(\s+)/) {
> + $leading_space = $1;
> + } else {
> + $leading_space = "";
> + }
> + }
> + $cont =~ s/^$leading_space//;
> + }
> + $contents .= $cont . "\n";
> + }
> +} else {
> + # i dont know - bad line?  ignore.
> + print STDERR "${file}:$.: warning: bad line: $_";
> + ++$warnings;
> +}
> +}
> +
> +
>  sub process_file($) {
>  my $file;
>  my $func;
>  my $initial_section_counter = $section_counter;
>  my ($orig_file) = @_;
> -m

Re: [PATCH 4/8] docs: kernel-doc: Move STATE_NAME processing into its own function

[Jani Nikula]

On Wed, 07 Feb 2018, Jonathan Corbet <cor...@lwn.net> wrote:
> Move this code out of process_file() in the name of readability and
> maintainability.
>
> Signed-off-by: Jonathan Corbet <cor...@lwn.net>

I admit I don't fully understand the semantics of perl parameter
passing, but looks okay.

Reviewed-by: Jani Nikula <jani.nik...@intel.com>

> ---
>  scripts/kernel-doc | 137 
> -
>  1 file changed, 72 insertions(+), 65 deletions(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 65150b7c8472..a27c7016f72d 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1793,13 +1793,81 @@ sub process_normal() {
>  }
>  }
>  
> +#
> +# STATE_NAME: Looking for the "name - description" line
> +#
> +sub process_name($$) {
> +my $file = shift;
> +my $identifier;
> +my $descr;
> +
> +if (/$doc_block/o) {
> + $state = STATE_DOCBLOCK;
> + $contents = "";
> + $new_start_line = $. + 1;
> +
> + if ( $1 eq "" ) {
> + $section = $section_intro;
> + } else {
> + $section = $1;
> + }
> +}
> +elsif (/$doc_decl/o) {
> + $identifier = $1;
> + if (/\s*([\w\s]+?)\s*-/) {
> + $identifier = $1;
> + }
>  
> + $state = STATE_BODY;
> + # if there's no @param blocks need to set up default section
> + # here
> + $contents = "";
> + $section = $section_default;
> + $new_start_line = $. + 1;
> + if (/-(.*)/) {
> + # strip leading/trailing/multiple spaces
> + $descr= $1;
> + $descr =~ s/^\s*//;
> + $descr =~ s/\s*$//;
> + $descr =~ s/\s+/ /g;
> + $declaration_purpose = $descr;
> + $state = STATE_BODY_MAYBE;
> + } else {
> + $declaration_purpose = "";
> + }
> +
> + if (($declaration_purpose eq "") && $verbose) {
> + print STDERR "${file}:$.: warning: missing initial short 
> description on line:\n";
> + print STDERR $_;
> + ++$warnings;
> + }
> +
> + if ($identifier =~ m/^struct/) {
> + $decl_type = 'struct';
> + } elsif ($identifier =~ m/^union/) {
> + $decl_type = 'union';
> + } elsif ($identifier =~ m/^enum/) {
> + $decl_type = 'enum';
> + } elsif ($identifier =~ m/^typedef/) {
> + $decl_type = 'typedef';
> + } else {
> + $decl_type = 'function';
> + }
> +
> + if ($verbose) {
> + print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
> + }
> +} else {
> + print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
> + " - I thought it was a doc line\n";
> + ++$warnings;
> + $state = STATE_NORMAL;
> +}
> +}
>  
>  sub process_file($) {
>  my $file;
> -my $identifier;
>  my $func;
> -my $descr;
>  my $initial_section_counter = $section_counter;
>  my ($orig_file) = @_;
>  my $leading_space;
> @@ -1823,69 +1891,8 @@ sub process_file($) {
>  while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
>   if ($state == STATE_NORMAL) {
>   process_normal();
> - } elsif ($state == STATE_NAME) {# this line is the function name 
> (always)
> - if (/$doc_block/o) {
> - $state = STATE_DOCBLOCK;
> - $contents = "";
> -$new_start_line = $. + 1;
> -
> - if ( $1 eq "" ) {
> - $section = $section_intro;
> - } else {
> - $section = $1;
> - }
> - }
> - elsif (/$doc_decl/o) {
> - $identifier = $1;
> - if (/\s*([\w\s]+?)\s*-/) {
> - $identifier = $1;
> - }
> -
> - $state = STATE_BODY;
> - # if there's no @param blocks need to set up default section
> - # here
> - $contents = "";
> - $section = $section_default;
> - $new_start_line = $. + 1;
> - if (/-(.*)/) {
> - # strip leading/trailing/multiple spaces
> - $descr= $1;
> - $descr =~ s/^\s*//;
> - $descr =~ s/\s*$//;
> - $descr =~ s/\s+/ /g;
> - $declaration_purpose = $descr;
> - $state = STATE_BODY_MAYBE;
> - } else {
> - $declaration_purpose = "

Re: [PATCH 2/8] docs: kernel-doc: Rename and split STATE_FIELD

[Jani Nikula]

On Wed, 07 Feb 2018, Jonathan Corbet <cor...@lwn.net> wrote:
> STATE_FIELD describes a parser state that can handle any part of a
> kerneldoc comment body; rename it to STATE_BODY to reflect that.
>
> The $in_purpose variable was a hidden substate of STATE_FIELD; get rid of
> it and make a proper state (STATE_BODY_MAYBE) instead.  This will make the
> subsequent process_file() splitup easier.
>
> Signed-off-by: Jonathan Corbet <cor...@lwn.net>

I really wanted to avoid leaving behind any evidence that I've ever
reviewed perl, but my sympathy for you updating the script won. But just
barely.

Reviewed-by: Jani Nikula <jani.nik...@intel.com>

> ---
>  scripts/kernel-doc | 22 +++---
>  1 file changed, 11 insertions(+), 11 deletions(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 5aa4ce211fc6..ad30c52f91ef 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -328,10 +328,11 @@ my $lineprefix="";
>  use constant {
>  STATE_NORMAL=> 0, # normal code
>  STATE_NAME  => 1, # looking for function name
> -STATE_FIELD => 2, # scanning field start
> -STATE_PROTO => 3, # scanning prototype
> -STATE_DOCBLOCK  => 4, # documentation block
> -STATE_INLINE=> 5, # gathering documentation outside main block
> +STATE_BODY_MAYBE=> 2, # body - or maybe more description
> +STATE_BODY  => 3, # the body of the comment
> +STATE_PROTO => 4, # scanning prototype
> +STATE_DOCBLOCK  => 5, # documentation block
> +STATE_INLINE=> 6, # gathering documentation outside main block
>  };
>  my $state;
>  my $in_doc_sect;
> @@ -1784,7 +1785,6 @@ sub process_file($) {
>  my $identifier;
>  my $func;
>  my $descr;
> -my $in_purpose = 0;
>  my $initial_section_counter = $section_counter;
>  my ($orig_file) = @_;
>  my $leading_space;
> @@ -1830,7 +1830,7 @@ sub process_file($) {
>   $identifier = $1;
>   }
>  
> - $state = STATE_FIELD;
> + $state = STATE_BODY;
>   # if there's no @param blocks need to set up default section
>   # here
>   $contents = "";
> @@ -1843,7 +1843,7 @@ sub process_file($) {
>   $descr =~ s/\s*$//;
>   $descr =~ s/\s+/ /g;
>   $declaration_purpose = $descr;
> - $in_purpose = 1;
> + $state = STATE_BODY_MAYBE;
>   } else {
>   $declaration_purpose = "";
>   }
> @@ -1875,7 +1875,7 @@ sub process_file($) {
>   ++$warnings;
>   $state = STATE_NORMAL;
>   }
> - } elsif ($state == STATE_FIELD) {   # look for head: lines, and 
> include content
> + } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) {
>   if (/$doc_sect/i) { # case insensitive for supported section names
>   $newsection = $1;
>   $newcontents = $2;
> @@ -1902,7 +1902,7 @@ sub process_file($) {
>   }
>  
>   $in_doc_sect = 1;
> - $in_purpose = 0;
> + $state = STATE_BODY;
>   $contents = $newcontents;
>  $new_start_line = $.;
>   while (substr($contents, 0, 1) eq " ") {
> @@ -1941,8 +1941,8 @@ sub process_file($) {
>   } else {
>   $contents .= "\n";
>   }
> - $in_purpose = 0;
> - } elsif ($in_purpose == 1) {
> + $state = STATE_BODY;
> + } elsif ($state == STATE_BODY_MAYBE) {
>   # Continued declaration purpose
>   chomp($declaration_purpose);
>   $declaration_purpose .= " " . $1;

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/8] docs: kernel-doc: Get rid of xml_escape() and friends

[Jani Nikula]

   dump_section($file, $section, xml_escape($contents));
> + dump_section($file, $section, $contents);
>   $section = $section_default;
>   $contents = "";
>   }
> @@ -1981,7 +1934,7 @@ sub process_file($) {
>   # @parameter line to signify start of description
>   if ($1 eq "") {
>   if ($section =~ m/^@/ || $section eq $section_context) {
> - dump_section($file, $section, xml_escape($contents));
> + dump_section($file, $section, $contents);
>   $section = $section_default;
>   $contents = "";
>  $new_start_line = $.;
> @@ -1992,7 +1945,7 @@ sub process_file($) {
>   } elsif ($in_purpose == 1) {
>   # Continued declaration purpose
>   chomp($declaration_purpose);
> - $declaration_purpose .= " " . xml_escape($1);
> + $declaration_purpose .= " " . $1;
>   $declaration_purpose =~ s/\s+/ /g;
>   } else {
>   my $cont = $1;
> @@ -2030,7 +1983,7 @@ sub process_file($) {
>   # Documentation block end */
>   } elsif (/$doc_inline_end/) {
>   if (($contents ne "") && ($contents ne "\n")) {
> - dump_section($file, $section, xml_escape($contents));
> + dump_section($file, $section, $contents);
>   $section = $section_default;
>   $contents = "";
>   }
> @@ -2057,7 +2010,7 @@ sub process_file($) {
>   $contents = $2;
>   if ($contents ne "") {
>   $contents .= "\n";
> - dump_section($file, $section, xml_escape($contents));
> + dump_section($file, $section, $contents);
>   $section = $section_default;
>   $contents = "";
>   }
> @@ -2072,7 +2025,7 @@ sub process_file($) {
>   } elsif ($state == STATE_DOCBLOCK) {
>   if (/$doc_end/)
>   {
> - dump_doc_section($file, $section, 
> xml_escape($contents));
> + dump_doc_section($file, $section, $contents);
>   $section = $section_default;
>   $contents = "";
>   $function = "";

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation/process: kernel maintainer PGP guide

[Jani Nikula]

On Tue, 30 Jan 2018, Konstantin Ryabitsev <konstan...@linuxfoundation.org> 
wrote:
> This guide is an adapted version of the more general "Protecting Code
> Integrity" guide written and maintained by The Linux Foundation IT for
> use with open-source projects. It provides the oft-lacking guidance on
> the following topics:
>
> - how to properly protect one's PGP keys to minimize the risks of them
>   being stolen and used maliciously to impersonate a kernel developer
> - how to configure Git to properly use GnuPG
> - when and how to use PGP with Git
> - how to verify fellow Linux Kernel developer identities
>
> I believe this document should live with the rest of the documentation
> describing proper processes one should follow when participating in
> kernel development. Placing it in a wiki on some place like kernel.org
> would be insufficient for a number of reasons -- primarily, because only
> a relatively small subset of maintainers have accounts on kernel.org,
> but also because even those who do rarely remember that such wiki
> exists. Keeping it with the rest of in-kernel docs should hopefully give
> it more visibility, but also help keep it up-to-date as tools and
> processes evolve.

FWIW, agreed on having this with the kernel documentation.

I can't say I reviewed it, but glancing through I didn't spot any errors
either. Lots of good stuff.

Just one nit, I think it would be better to move the Maintainer: bit
from the end near the top as a reStructuredText field list. See 'git
grep :Author:' under Documentation for examples. Could even add a
MAINTAINERS entry to improve your chances of being Cc'd on changes.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: kernel.org documentation link (was Re: Protecting code integrity with PGP)

[Jani Nikula]

On Fri, 19 Jan 2018, Konstantin Ryabitsev <konstan...@linuxfoundation.org> 
wrote:
> On 2018-01-19 03:37 AM, Jani Nikula wrote:
>> On a side note, I was browsing for the generated kernel documentation at
>> https://www.kernel.org/ and realized that AFAICT there are no links to
>> https://www.kernel.org/doc/ or https://www.kernel.org/doc/html/latest/.
>> 
>> The former could use some love, but I think the latter is nice enough to
>> warrant a link from the main page.
>
> You're right, it's an oversight that is now fixed, see www.kernel.org.

Great, many thanks!

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Protecting code integrity with PGP (kernel developer version)

[Jani Nikula]

On Thu, 18 Jan 2018, Randy Dunlap <rdun...@infradead.org> wrote:
> On 01/18/2018 06:09 AM, Jani Nikula wrote:
>> On Thu, 11 Jan 2018, Konstantin Ryabitsev <konstan...@linuxfoundation.org> 
>> wrote:
>>> On Wed, Jan 10, 2018 at 02:05:16PM -0700, Jonathan Corbet wrote:
>>>>> Does such document belong with the rest of the kernel docs in the 
>>>>> tree,
>>>>> or should it remain fully external? I'll be happy to port it to RST if
>>>>> you think it should live alongside other documents like coding
>>>>> standards.
>>>>
>>>> My immediate impression is that there is a lot of useful information
>>>> there, but quite a bit of it covers topics that are somewhat peripheral
>>>> to kernel development itself.  I fear it would languish because few would
>>>> think to look for it there.  Thus, my first inclination is external.
>>>>
>>>> That said, if others want it in the docs tree, I'll happily take it.  As
>>>> I said, there's lots of good stuff there.
>>>
>>> Yeah, I was going to have a much slimmer version for the kernel devs.
>>>
>>> Let me do this -- I'll go ahead and produce the document I think would 
>>> be good for kernel devs, based on the more generic document I mentioned 
>>> earlier. Then I will get in touch again so we can see if that version is
>>> something that should go into the doc tree or continue to live 
>>> externally. Converting from .md into .rst is straightforward enough.
>> 
>> If you all choose to host it externally after all, I think the kernel
>> documentation should at least have a minimal document pointing people at
>> the external documentation.
>
> and/or somewhere on wiki.kernel.org.

On a side note, I was browsing for the generated kernel documentation at
https://www.kernel.org/ and realized that AFAICT there are no links to
https://www.kernel.org/doc/ or https://www.kernel.org/doc/html/latest/.

The former could use some love, but I think the latter is nice enough to
warrant a link from the main page.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Protecting code integrity with PGP (kernel developer version)

[Jani Nikula]

On Thu, 11 Jan 2018, Konstantin Ryabitsev <konstan...@linuxfoundation.org> 
wrote:
> On Wed, Jan 10, 2018 at 02:05:16PM -0700, Jonathan Corbet wrote:
>>> Does such document belong with the rest of the kernel docs in the 
>>> tree,
>>> or should it remain fully external? I'll be happy to port it to RST if
>>> you think it should live alongside other documents like coding
>>> standards.
>>
>>My immediate impression is that there is a lot of useful information
>>there, but quite a bit of it covers topics that are somewhat peripheral
>>to kernel development itself.  I fear it would languish because few would
>>think to look for it there.  Thus, my first inclination is external.
>>
>>That said, if others want it in the docs tree, I'll happily take it.  As
>>I said, there's lots of good stuff there.
>
> Yeah, I was going to have a much slimmer version for the kernel devs.
>
> Let me do this -- I'll go ahead and produce the document I think would 
> be good for kernel devs, based on the more generic document I mentioned 
> earlier. Then I will get in touch again so we can see if that version is
> something that should go into the doc tree or continue to live 
> externally. Converting from .md into .rst is straightforward enough.

If you all choose to host it externally after all, I think the kernel
documentation should at least have a minimal document pointing people at
the external documentation.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] doc: fix code snippet build warnings

[Jani Nikula]

On Tue, 16 Jan 2018, Markus Heiser <markus.hei...@darmarit.de> wrote:
>> Am 16.01.2018 um 11:22 schrieb Jani Nikula <jani.nik...@linux.intel.com>:
>> 
>> On Wed, 10 Jan 2018, Jonathan Corbet <cor...@lwn.net> wrote:
>>> On Wed, 10 Jan 2018 15:04:53 +1100
>>> "Tobin C. Harding" <m...@tobin.cc> wrote:
>>> 
>>>> Posting as RFC in the hope that someone knows how to massage sphinx
>>>> correctly to fix this patch.
>>>> 
>>>> Currently function kernel-doc contains a multi-line code snippet. This
>>>> is causing sphinx to emit 5 build warnings
>>>> 
>>>>WARNING: Unexpected indentation.
>>>>WARNING: Unexpected indentation.
>>>>WARNING: Block quote ends without a blank line; unexpected unindent.
>>>>WARNING: Block quote ends without a blank line; unexpected unindent.
>>>>WARNING: Inline literal start-string without end-string.
>>>> 
>>>> And the snippet is not rendering correctly in HTML.
>>>> 
>>>> We can stop shpinx complaining by using '::' instead of the currently
>>>> used '``' however this still does not render correctly in HTML. The
>>>> rendering is [arguably] better but still incorrect. Sphinx renders two
>>>> function calls thus:
>>>> 
>>>>:c:func:`rcu_read_lock()`;
>>>> 
>>>> The rest of the snippet does however have correct spacing.
>>> 
>>> The behavior when `` was used is not surprising, that really just does a
>>> font change.  Once you went with a literal block (with "::") though, the
>>> situation changes a bit.  That really should work.
>>> 
>>> I looked a bit.  This isn't a sphinx (or "shpinx" :) problem, the bug is
>>> in kernel-doc.  Once we go into the literal mode, it shouldn't be
>>> screwing around with the text anymore.  Of course, kernel-doc doesn't
>>> understand enough RST to know that.  I'm a little nervous about trying to
>>> teach it more, but maybe we have to do that; we should certainly be able
>>> to put code snippets into the docs and have them come through unmolested.
>> 
>> I think eventually the Right Thing would be to move most of kernel-doc's
>> mucking of the comments (i.e. highlights) into kernel-doc the Sphinx
>> extension. I've toyed with the idea, but it's not as trivial as I would
>> like it to be.
>> 
>> Basically it involves flagging all the kernel-doc nodes during the read
>> phase, and registering handlers to post process the doctrees. At that
>> stage, it's no longer simple regexp replaces, it's replacing doctree
>> nodes with ones that have reference nodes within them. It's more
>> complicated,
>
> Hi Jani, my thoughts about:  
>
> 1.) The reST syntax [1] (the parser part) is not *extendable*, we
> can only add new roles [2] or directives.

Right, but we've *already* extended it using kernel-doc anyway. I'm just
suggesting a way to do that *after* all other rst parsing has been
done. It's much easier to not confuse the rst parser this way. And we
can trivially skip reference nodes or bold text etc. already created by
Sphinx. And we can limit this to nodes generated from kernel-doc
comments if we want.

So for example, we can check if a text node contains, say, "struct foo",
check if struct foo documentation exists, and turn that into a reference
automatically. In most cases that's the right thing to do. Same with
function() stuff. And even when it's actually wrong, it doesn't screw up
the rendering like in the example in this thread, but rather just
generates a bogus link.

BR,
Jani.

>
> 2.) the kernel-doc syntax is weak and ambiguous. This
> remains mainly in tagging only with a start-tag or only with a end-tag 
> e.g:
>
> * sectioning:   "Return:" --> end-tag just ":"
> * fields:   "@arg1:"  --> better
> * highlight/ref: start tag [@%$&] / no end tag
>
> even if I don't know how (1.), if the highlight-syntax becomes a part
> of the reST syntax we have to quote [@%$&] elsewhere. This will break
> with valid reST documents which is unacceptable.
>
> Thats why I think we need to pre-parse highlighting in the kernel-doc
> Perl script, even if it is a bit hackish (how should it be otherwise,
> if the syntax is already hackish). I haven't had the time to implement
> such a highlight parser right now, but this would be the first shot of
> mine. 
>
> An alternative might be to use roles [2] but this means we have to
> break with the the kernel-doc (highlight) syntax which is IMO also
> un

Re: [RFC] doc: fix code snippet build warnings

[Jani Nikula]

On Thu, 11 Jan 2018, "Tobin C. Harding" <m...@tobin.cc> wrote:
> On Wed, Jan 10, 2018 at 02:59:58PM -0700, Jonathan Corbet wrote:
>> ...rather than adding a separate "::" line, you can just
>> s/follows:/follows::/ and the Right Thing will happen (to the same extent
>> that it does now, anyway.
>
> Except that it will render as
>
>   kill_dependency().  It could be used as follows
>
> instead of
>   kill_dependency().  It could be used as follows:
>
> (note: final colon)

Quoting [1], "The :: may be tacked onto the very end of any
paragraph. The :: will be omitted if it is preceded by whitespace. The
:: will be converted to a single colon if preceded by text"

BR,
Jani.


[1] http://docutils.sourceforge.net/docs/user/rst/quickref.html#literal-blocks



-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] doc: fix code snippet build warnings

[Jani Nikula]

On Wed, 10 Jan 2018, Jonathan Corbet <cor...@lwn.net> wrote:
> On Wed, 10 Jan 2018 15:04:53 +1100
> "Tobin C. Harding" <m...@tobin.cc> wrote:
>
>> Posting as RFC in the hope that someone knows how to massage sphinx
>> correctly to fix this patch.
>> 
>> Currently function kernel-doc contains a multi-line code snippet. This
>> is causing sphinx to emit 5 build warnings
>> 
>>  WARNING: Unexpected indentation.
>>  WARNING: Unexpected indentation.
>>  WARNING: Block quote ends without a blank line; unexpected unindent.
>>  WARNING: Block quote ends without a blank line; unexpected unindent.
>>  WARNING: Inline literal start-string without end-string.
>> 
>> And the snippet is not rendering correctly in HTML.
>> 
>> We can stop shpinx complaining by using '::' instead of the currently
>> used '``' however this still does not render correctly in HTML. The
>> rendering is [arguably] better but still incorrect. Sphinx renders two
>> function calls thus:
>> 
>>  :c:func:`rcu_read_lock()`;
>> 
>> The rest of the snippet does however have correct spacing.
>
> The behavior when `` was used is not surprising, that really just does a
> font change.  Once you went with a literal block (with "::") though, the
> situation changes a bit.  That really should work.
>
> I looked a bit.  This isn't a sphinx (or "shpinx" :) problem, the bug is
> in kernel-doc.  Once we go into the literal mode, it shouldn't be
> screwing around with the text anymore.  Of course, kernel-doc doesn't
> understand enough RST to know that.  I'm a little nervous about trying to
> teach it more, but maybe we have to do that; we should certainly be able
> to put code snippets into the docs and have them come through unmolested.

I think eventually the Right Thing would be to move most of kernel-doc's
mucking of the comments (i.e. highlights) into kernel-doc the Sphinx
extension. I've toyed with the idea, but it's not as trivial as I would
like it to be.

Basically it involves flagging all the kernel-doc nodes during the read
phase, and registering handlers to post process the doctrees. At that
stage, it's no longer simple regexp replaces, it's replacing doctree
nodes with ones that have reference nodes within them. It's more
complicated, but at that stage we can ignore stuff that should stay
verbatim. I think it's also possible to check that the reference targets
actually exist. In short, at that phase we have all the knowledge about
the rst structure, parsed by Sphinx, and we don't have to duplicate that
knowledge in kernel-doc the perl script.

Note that this has nothing to do with swithing to Python based
kernel-doc suggested by Markus previously.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] Tools to fix/prevent broken Documentation file references

[Jani Nikula]

On Tue, 09 Jan 2018, Genki Sky <s...@genki.is> wrote:
> I personally am happy with the more organized Documentation/ tree. But
> as everyone knows, there's still a bit of breakage. Not the most fun
> to fix. However, it seems some tools could help ease this process /
> prevent future breakage. I listed a couple below. If either seem worth
> pursuing, I'd be happy to take up implementing them. Else, or if
> they've already been discussed, please let me know.

Related, see scripts/documentation-file-ref-check.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 1/1] runchecks: Generalize make C={1,2} to support multiple checkers

[Jani Nikula]

On Thu, 04 Jan 2018, Knut Omang <knut.om...@oracle.com> wrote:
> On Thu, 2018-01-04 at 17:50 +0200, Jani Nikula wrote:
>> On Thu, 04 Jan 2018, Knut Omang <knut.om...@oracle.com> wrote:
>> > Add scripts/runchecks which has generic support for running
>> > checker tools in a convenient and user friendly way that
>> > the author hopes can contribute to rein in issues detected
>> > by these tools in a manageable and convenient way.
>> >
>> > scripts/runchecks provides the following basic functionality:
>> >
>> > * Makes it possible to selectively suppress output from individual
>> >   checks on a per file or per subsystem basis.
>> > * Unifies output and suppression input from different tools
>> >   by providing a single unified syntax and presentation for the
>> >   underlying tools in the style of "scripts/checkpatch.pl --show-types".
>> > * Allows selective run of one, or more (or all) configured tools
>> >   for each file.
>> >
>> > In the Makefile system, the sparse specific setup has been replaced
>> > by setup for runchecks.
>> >
>> > This version of runchecks together with a "global" configuration
>> > file in "scripts/runchecks.cfg" supports sparse, checkpatch, and checkdoc,
>> > a trivial abstraction above a call to 'kernel-doc -none'.
>> > It also supports forwarding calls to coccicheck for coccinelle support
>> > but this is not quite as worked through as the three other checkers,
>> > mainly because of lack of error data as all checks pass by default
>> > right now.
>> >
>> > The code is designed to be easily extensible to support more checkers
>> > as they emerge, and some generic checker support is even available
>> > just via simple additions to "scripts/runchecks.cfg".
>> >
>> > The runchecks program unifies configuration, processing
>> > and output for multiple checker tools to make them
>> > all run as part of the C=1 or C=2 option to make.
>> >
>> > Currently with full support and unified behaviour for
>> > sparse: sparse
>> > checkpatch: scripts/checkpatch.pl
>> > checkdoc:   kernel-doc -none
>> >
>> > In principle supported but not unified in output(yet):
>> > coccinelle: scripts/coccicheck
>> >
>> > Introduces a new documentation section titled
>> > "Makefile support for running checkers"
>> >
>> > Also updates documentation for the make C= option
>> > in some other doc files, as the behaviour has
>> > been changed to be less sparse specific and more
>> > generic. The coccinelle documentation also had the
>> > behaviour of C=1 and C=2 swapped.
>> 
>> I'm surprised the commit message and the provided documentation say
>> nothing about using CHECK=foo on the command line. That already supports
>> arbitrary checkers. 
>
> The problem, highlighted by Jim Davis in
>
> https://lkml.org/lkml/2017/11/20/638
>
> is that the current solution isn't flexible enough - that discussion 
> is what lead me to this reimplementation of what I originally intended 
> to be a checkpatch only solution.
>
>> How does this relate to that? Is this supposed to be
>> a complete replacement? Or what?
>
> It has evolved into a complete replacement of the intention of CHECK.
>
>> 'make help' also references $CHECK, and this patch doesn't update the
>> help text.
>
> I realize now that this needs to be handled in some way due to the way I 
> split the 
> arguments with '--' - the intention was to keep it for bw compatibility.
>
> It would be good to know if people rely on using CHECK with C={1,2} for 
> anything beside the checkers supported by runchecks today, if not, 
> it could either be removed or simply replace by an expansion into a 
> '--run:$CHECK'
> argument to runchecks 
>
> Then runchecks' implicit method of declaring 
>
> checker  
>
> in scripts/runchecks.cfg could be used for people with checkers that
> need no further input/output adaptation.
>
> Further suggestions appreciated on this matter.

FWIW, I'd think it would be sufficient the documentation ('make help'
and your runchecks.rst et al) gets updated to reflect the changes to
$CHECK. But up to whoever is the maintainer here.

>
>> > Signed-off-by: Knut Omang <knut.om...@oracle.com>
>> > Reviewed-by: Håkon Bugge <haakon.bu...@oracle.com>
>> > Reviewed-by: Åsmund Østvold <asmund.ostv...@oracle.com>
>> > Reviewed-by: John Haxby <

Re: [PATCH v3 1/1] runchecks: Generalize make C={1,2} to support multiple checkers

[Jani Nikula]

On Thu, 04 Jan 2018, Knut Omang  wrote:
> Add scripts/runchecks which has generic support for running
> checker tools in a convenient and user friendly way that
> the author hopes can contribute to rein in issues detected
> by these tools in a manageable and convenient way.
>
> scripts/runchecks provides the following basic functionality:
>
> * Makes it possible to selectively suppress output from individual
>   checks on a per file or per subsystem basis.
> * Unifies output and suppression input from different tools
>   by providing a single unified syntax and presentation for the
>   underlying tools in the style of "scripts/checkpatch.pl --show-types".
> * Allows selective run of one, or more (or all) configured tools
>   for each file.
>
> In the Makefile system, the sparse specific setup has been replaced
> by setup for runchecks.
>
> This version of runchecks together with a "global" configuration
> file in "scripts/runchecks.cfg" supports sparse, checkpatch, and checkdoc,
> a trivial abstraction above a call to 'kernel-doc -none'.
> It also supports forwarding calls to coccicheck for coccinelle support
> but this is not quite as worked through as the three other checkers,
> mainly because of lack of error data as all checks pass by default
> right now.
>
> The code is designed to be easily extensible to support more checkers
> as they emerge, and some generic checker support is even available
> just via simple additions to "scripts/runchecks.cfg".
>
> The runchecks program unifies configuration, processing
> and output for multiple checker tools to make them
> all run as part of the C=1 or C=2 option to make.
>
> Currently with full support and unified behaviour for
> sparse: sparse
> checkpatch: scripts/checkpatch.pl
> checkdoc:   kernel-doc -none
>
> In principle supported but not unified in output(yet):
> coccinelle: scripts/coccicheck
>
> Introduces a new documentation section titled
> "Makefile support for running checkers"
>
> Also updates documentation for the make C= option
> in some other doc files, as the behaviour has
> been changed to be less sparse specific and more
> generic. The coccinelle documentation also had the
> behaviour of C=1 and C=2 swapped.

I'm surprised the commit message and the provided documentation say
nothing about using CHECK=foo on the command line. That already supports
arbitrary checkers. How does this relate to that? Is this supposed to be
a complete replacement? Or what?

'make help' also references $CHECK, and this patch doesn't update the
help text.

> Signed-off-by: Knut Omang 
> Reviewed-by: Håkon Bugge 
> Reviewed-by: Åsmund Østvold 
> Reviewed-by: John Haxby 
> ---
>  Documentation/dev-tools/coccinelle.rst |  12 +-
>  Documentation/dev-tools/index.rst  |   1 +-
>  Documentation/dev-tools/runchecks.rst  | 215 -
>  Documentation/dev-tools/sparse.rst |  30 +-
>  Documentation/kbuild/kbuild.txt|   9 +-
>  Makefile   |  23 +-
>  scripts/Makefile.build |   4 +-
>  scripts/runchecks  | 734 ++-
>  scripts/runchecks.cfg  |  63 ++-
>  scripts/runchecks_help.txt |  43 ++-

Please get rid of runchecks_help.txt and use the usual python mechanisms
to specify and parse command line options, with their help texts,
including automated --help output. This keeps the implementation and the
help together, with hopes they'll actually stay in sync. Please don't
hand roll argument parsers in python.

BR,
Jani.

>  10 files changed, 1114 insertions(+), 20 deletions(-)
>  create mode 100644 Documentation/dev-tools/runchecks.rst
>  create mode 100755 scripts/runchecks
>  create mode 100644 scripts/runchecks.cfg
>  create mode 100644 scripts/runchecks_help.txt
>
> diff --git a/Documentation/dev-tools/coccinelle.rst 
> b/Documentation/dev-tools/coccinelle.rst
> index 94f41c2..c98cc44 100644
> --- a/Documentation/dev-tools/coccinelle.rst
> +++ b/Documentation/dev-tools/coccinelle.rst
> @@ -157,17 +157,19 @@ For example, to check drivers/net/wireless/ one may 
> write::
>  
>  make coccicheck M=drivers/net/wireless/
>  
> -To apply Coccinelle on a file basis, instead of a directory basis, the
> -following command may be used::
> +To apply Coccinelle as the only checker on a file basis,
> +instead of a directory basis, the following command may be used::
>  
> -make C=1 CHECK="scripts/coccicheck"
> +make C=2 CF="--run:coccicheck"
>  
> -To check only newly edited code, use the value 2 for the C flag, i.e.::
> +To check only newly edited code, use the value 1 for the C flag, i.e.::
>  
> -make C=2 CHECK="scripts/coccicheck"
> +make C=1 CF="--run:coccicheck"
>  
>  In these modes, which works on a file basis, there is no information
>  about semantic patches displayed, and no commit message proposed.
> +For 

Re: Documentation license

[Jani Nikula]

On Thu, 14 Dec 2017, Matthew Wilcox <wi...@infradead.org> wrote:
> 1. How does one add an SPDX tag to an rst file?

Do we want the SPDX tags visible in the generated documentation or not?

If not, you have to put it in an rst comment:

.. SPDX-License-Identifier: GPL-2.0

If yes, I'd go for using bibliographic data field lists [1]. They can be
and are already used for authorship and copyright, for example
Documentation/driver-api/device-io.rst which is rendered like [2]. There
are some alternatives for the field names, though none of the
"registered field names" seem to apply. For example:

:License: SPDX-License-Identifier: GPL-2.0
:SPDX: SPDX-License-Identifier: GPL-2.0
:SPDX-License-Identifier: GPL-2.0


BR,
Jani.


[1] 
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#field-lists
[2] https://www.kernel.org/doc/html/latest/driver-api/device-io.html


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] docs: Remove "could not extract kernel version" warning

[Jani Nikula]

On Mon, 11 Dec 2017, Randy Dunlap <rdun...@infradead.org> wrote:
> On 12/11/2017 02:24 PM, Jonathan Corbet wrote:
>> This warning will happen for every normal kernel docs build and doesn't
>> carry any useful information.  Should anybody actually depend on this
>> "version" variable (which isn't clear to me), the "unknown version" value
>> will be clue enough.
>
> Yay.  I looked at that last week and got nowhere with it.

The whole try block was for when sphinx-build is run directly, e.g. when
run by Read the Docs or manually on the command line. But looking at all
the Makefile sauce we've accumulated, we're probably way, *way* beyond
the point where building the docs is in any way feasible by running
sphinx-build directly.

The Makefile passes version and release on the sphinx-build command line
in our normal build, so we could just remove the try block
altogether. It's more like a fallback hack anyway.

The version shows up in the built documentation, depending on the theme.

Nothing wrong with this patch, but could go further.

BR,
Jani.


>
>> Signed-off-by: Jonathan Corbet <cor...@lwn.net>
>> ---
>>  Documentation/conf.py | 1 -
>>  1 file changed, 1 deletion(-)
>> 
>> diff --git a/Documentation/conf.py b/Documentation/conf.py
>> index 63857d33778c..62ac5a9f3a9f 100644
>> --- a/Documentation/conf.py
>> +++ b/Documentation/conf.py
>> @@ -88,7 +88,6 @@ finally:
>>  if makefile_version and makefile_patchlevel:
>>  version = release = makefile_version + '.' + makefile_patchlevel
>>  else:
>> -sys.stderr.write('Warning: Could not extract kernel version\n')
>>  version = release = "unknown version"
>>  
>>  # The language for content autogenerated by Sphinx. Refer to documentation
>> 

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] docs: add submitting-pull-requests.rst

[Jani Nikula]

On Tue, 21 Nov 2017, "Tobin C. Harding" <m...@tobin.cc> wrote:
> On Wed, Nov 15, 2017 at 04:09:32PM +0200, Jani Nikula wrote:
>> On Wed, 15 Nov 2017, "Tobin C. Harding" <m...@tobin.cc> wrote:
>> > Original email thread 
>> >
>> > https://lkml.org/lkml/2017/11/14/184
>> 
>> Please use http://lkml.kernel.org/r/20171114110500.ga21...@kroah.com so
>> people can find the messages using the message-id.
>
> How did you generate this URL? Is this the format that should be used
> whenever linking to LKML messages i.e when including links in mail being
> sent to LKML?

See https://lkml.kernel.org/. It's just a base URL + message-id of the
message. (In my MUA, I can just hit a few keys and get the URL stashed
to the clipboard.)

The message-id based URL lets people find the message using their MUA
instead of having to go to some horrendous web site. But it still lets
people who prefer web sites use them.

Moreover, if an archive goes down, this makes it possible to still find
the message.



BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] docs: add submitting-pull-requests.rst

[Jani Nikula]

t;> > help
>> > +determining what you want to pull, and what to base the pull against (to 
>> > show
>> > +the correct changes to be pulled and the diffstat.)
>> > +
>> > +The following command(s) will generate a pull request:
>> > +
>> > +  
>> > $TREE=git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc.git/
>> 
>> I don't believe that $ is correct
>
> Bad Tobin, no biscuit. (read: cookie)
>
>> > +  git request-pull master $TREE char-misc-4.15-rc1
>> > +
>> > +This is asking git to compare the difference from the 
>> > 'char-misc-4.15-rc1' tag
>> > +location, to the head of the 'master' branch (which in my case points to 
>> > the
>> > +last location in Linus's tree that I diverged from, usually a -rc 
>> > release).
>> > +
>> > +Note: please use the git protocol (for justification from Linus see 
>> > referenced
>> > +email thread).
>> 
>> We need a reference to that thread.
>> 
>> > +If the char-misc-4.15-rc1 tag is not present in the repo that I am asking 
>> > to be
>> > +pulled from, git will complain saying it is not there, a handy way to 
>> > remember
>> > +to actually push it to a public location.
>> > +
>> > +The output of 'git request-pull' will contain the location of the git 
>> > tree and
>> > +specific tag to pull from, and the full text description of that tag 
>> > (which is
>> > +why you need to provide good information in that tag.)  It will also 
>> > create a
>> > +diffstat of the pull request, and a shortlog of the individual commits 
>> > that the
>> > +pull request will provide.
>> > +
>> > +
>> > +References
>> > +--
>> > +
>> > +The thread that this document is based on:
>> > +
>> > +  https://lkml.org/lkml/2017/11/14/184
>> 
>> Ah, there's that reference.  I think it should be at the top before you
>> first start quoting from it.
>
> Perhaps (at start of document)
>
> This document was written by Tobin C. Harding (not an experienced
> maintainer) primarily from emails by Greg Kroah-Hartman and Linus
> Torvalds. Suggestions and fixes by Jonathan Corbet. Misrepresentation
> was unintentional but inevitable, please direct abuse to "Tobin
> C. Harding" <m...@tobin.cc>. 
>
> Original email thread 
>
> https://lkml.org/lkml/2017/11/14/184

Please use http://lkml.kernel.org/r/20171114110500.ga21...@kroah.com so
people can find the messages using the message-id.

Please consider using reStructuredText references instead of a
semi-random looking indented block.

BR,
Jani.


>
>> I think there's something missing here: what do you do with that output
>> from 'git request-pull'?  There should be a little section on emailing it
>> to the relevant upstream maintainer and how to decide where to copy the
>> request to.  Pull requests should always be copied to a public list so that
>> others know that the request has been made.  Some guidance on subject-line
>> formatting would be good; as I recall, Linus filters mail that says "git"
>> or "pull" specially.  I might also add something about how to know when the
>> pull has happened (sign up to the commits list if nothing else).
>> 
>> Thanks for doing this,
>
> Cheers Jon, nice to work with you.
>
> Tobin.
> --
> To unsubscribe from this list: send the line "unsubscribe linux-doc" in
> the body of a message to majord...@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Check all .c files for bad kernel-doc comments

[Jani Nikula]

On Mon, 30 Oct 2017, Matthew Wilcox <wi...@infradead.org> wrote:
> On Mon, Oct 30, 2017 at 05:19:18PM +0200, Jani Nikula wrote:
>> Related, there was also a script to do reStructuredText lint style
>> checks in addition to the kernel-doc checks using make CHECK and
>> C=1. See http://mid.mail-archive.com/87h98quc1w.fsf@intel.com
>
> I don't really care which patch goes in.  If I understand your python
> script correctly, it relies on having various python packages installed.
> Unless we're going to switch kernel-doc over to being written in python,
> I'd prefer to not require additional dependencies.

I think your patch has a much better chance of getting enabled by
default in the long run, so I'd prefer that. I've also kind of dropped
the ball on my script... but thought it might be interesting.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Check all .c files for bad kernel-doc comments

[Jani Nikula]

On Mon, 30 Oct 2017, Matthew Wilcox <wi...@infradead.org> wrote:
> On Mon, Oct 30, 2017 at 12:40:20PM +0900, Masahiro Yamada wrote:
>> 2017-10-28 4:41 GMT+09:00 Matthew Wilcox <wi...@infradead.org>:
>> > Implement a '-none' output mode for kernel-doc which will only output
>> > warning messages, and suppresses the warning message about there being
>> > no kernel-doc in the file.  Add it to the rule to build .o files from .c
>> > files, so it will check all .c files that have been modified.
>> >
>> > Adds about 1300 warnings to my build, but will hopefully discourage
>> > people from introducing more kerneldoc mistakes.
>> 
>> Basically, I think this is good,
>> but it is controversial to sprinkle warnings by default.
>
> Yes, it is.  I just got three nastygrams from 01.org ;-)
>
> But if it's not turned on by default, then people aren't going to notice
> when they introduce new warnings.  I think it needs to be up to someone
> like Andrew or Linus to decide when to add these warnings by default.
> Maybe we should do something like you have below for now, then work on
> cleaning up a few hundred of these warnings, then enable this by default?
>
> Thanks for looking at this!
>
>> Maybe,
>> 
>> ifeq ($(KBUILD_ENABLE_EXTRA_GCC_CHECKS),)
>> cmd_checkdoc = $(srctree)/scripts/kernel-doc -none $< ;
>> endif
>> 
>> 
>> so that this is checked only when W=... is given?

Related, there was also a script to do reStructuredText lint style
checks in addition to the kernel-doc checks using make CHECK and
C=1. See [1].


BR,
Jani.


[1] http://mid.mail-archive.com/87h98quc1w.fsf@intel.com




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

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: ReST questions

[Jani Nikula]

On Sun, 22 Oct 2017, Randy Dunlap <rdun...@infradead.org> wrote:
> (2) It wants to preface each "function" in the "art" with ":c:func:" and put
> back-quote marks around each function name, like `finish()`.  That makes the 
> ASCII art
> unreadable.
>
> I have tried :: by itself and .. code-block:: none
> without success.
>
> Is there a way to prevent this :c:func: enhancing?

That's a hard one, I'm afraid. We do the substitutions in kernel-doc the
perl script, at a level where we don't want to parse reStructuredText to
figure out where the substitutions are fine and where they're
not. Worse, we don't even have any way to escape them.

The right fix would be to remove the substitutions from kernel-doc the
perl script altogether, and apply them after all the reStructuredText
parsing is done, where we have access to the doctree structures
[1]. Then we could be smarter about where we change them to
cross-references. We wouldn't be doing simple regexp conversions, we'd
be wrapping pieces of text in doctree reference nodes. I think it should
even be possible to complain about references to non-existing targets.

SMOP.


BR,
Jani.


[1] http://docutils.sourceforge.net/docs/ref/doctree.html


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Documentation: add Kernel Driver Statement to the kernel

[Jani Nikula]

On Sat, 14 Oct 2017, "gre...@linuxfoundation.org" <gre...@linuxfoundation.org> 
wrote:
> And really, all news one should be in correct markdown format, as it is
> almost identical to a "normal" text file.  Heck, it really is just a
> "plain" textfile, you can read it as-such, right?

*cough* reStructuredText *cough*

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 3/8] Documentation: fix ref to workqueue content

[Jani Nikula]

On Thu, 12 Oct 2017, Tom Saeger <tom.sae...@oracle.com> wrote:
> Signed-off-by: Tom Saeger <tom.sae...@oracle.com>
> ---
>  .../RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.html | 2 
> +-

Someone(tm) should convert the last three html files to rst one of these
days!

In the mean time, I guess this is good enough.

BR,
Jani.

>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git 
> a/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.html
>  
> b/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.html
> index e5d0bbd0230b..7394f034be65 100644
> --- 
> a/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.html
> +++ 
> b/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.html
> @@ -527,7 +527,7 @@ grace period also drove it to completion.
>  This straightforward approach had the disadvantage of needing to
>  account for POSIX signals sent to user tasks,
>  so more recent implemementations use the Linux kernel's
> - href="https://www.kernel.org/doc/Documentation/workqueue.txt;>workqueues.
> + href="https://www.kernel.org/doc/Documentation/core-api/workqueue.rst;>workqueues.
>  
>  
>  The requesting task still does counter snapshotting and funnel-lock

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation: add script and build target to check for broken file references

[Jani Nikula]

On Mon, 09 Oct 2017, Tom Saeger <tom.sae...@oracle.com> wrote:
> On Mon, Oct 09, 2017 at 03:26:15PM +0000, Jani Nikula wrote:
>> Add a simple script and build target to do a treewide grep for
>> references to files under Documentation, and report the non-existing
>> file in stderr. It tries to take into account punctuation not part of
>> the filename, and wildcards, but there are bound to be false positives
>> too. Mostly seems accurate though.
>> 
>> We've moved files around enough to make having this worthwhile.
>> 
>> Signed-off-by: Jani Nikula <jani.nik...@intel.com>
>> ---
>>  Documentation/Makefile   |  4 
>>  Makefile |  2 +-
>>  scripts/documentation-file-ref-check | 15 +++
>>  3 files changed, 20 insertions(+), 1 deletion(-)
>>  create mode 100755 scripts/documentation-file-ref-check
>> 
>> diff --git a/Documentation/Makefile b/Documentation/Makefile
>> index 85f7856f0092..f4f5aecb81d1 100644
>> --- a/Documentation/Makefile
>> +++ b/Documentation/Makefile
>> @@ -97,6 +97,9 @@ endif # HAVE_SPHINX
>>  # The following targets are independent of HAVE_SPHINX, and the rules should
>>  # work or silently pass without Sphinx.
>>  
>> +refcheckdocs:
>> +$(Q)cd $(srctree);scripts/documentation-file-ref-check
>> +
>>  cleandocs:
>>  $(Q)rm -rf $(BUILDDIR)
>>  $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) 
>> $(build)=Documentation/media clean
>> @@ -109,6 +112,7 @@ dochelp:
>>  @echo  '  epubdocs- EPUB'
>>  @echo  '  xmldocs - XML'
>>  @echo  '  linkcheckdocs   - check for broken external links (will 
>> connect to external hosts)'
>> +@echo  '  refcheckdocs- check for references to non-existing files 
>> under Documentation'
>>  @echo  '  cleandocs   - clean all generated files'
>>  @echo
>>  @echo  '  make SPHINXDIRS="s1 s2" [target] Generate only docs of folder 
>> s1, s2'
>> diff --git a/Makefile b/Makefile
>> index cf007a31d575..a97e70a9a39c 100644
>> --- a/Makefile
>> +++ b/Makefile
>> @@ -1454,7 +1454,7 @@ $(help-board-dirs): help-%:
>>  
>>  # Documentation targets
>>  # 
>> ---
>> -DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs 
>> linkcheckdocs
>> +DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs 
>> linkcheckdocs refcheckdocs
>>  PHONY += $(DOC_TARGETS)
>>  $(DOC_TARGETS): scripts_basic FORCE
>>  $(Q)$(MAKE) $(build)=Documentation $@
>> diff --git a/scripts/documentation-file-ref-check 
>> b/scripts/documentation-file-ref-check
>> new file mode 100755
>> index ..bc1659900e89
>> --- /dev/null
>> +++ b/scripts/documentation-file-ref-check
>> @@ -0,0 +1,15 @@
>> +#!/bin/sh
>> +# Treewide grep for references to files under Documentation, and report
>> +# non-existing files in stderr.
>> +
>> +for f in $(git ls-files); do
>> +for ref in $(grep -ho "Documentation/[A-Za-z0-9_.,~/*+-]*" "$f"); do
>> +# presume trailing . and , are not part of the name
>> +ref=${ref%%[.,]}
>> +
>> +# use ls to handle wildcards
>> +if ! ls $ref >/dev/null 2>&1; then
>> +echo "$f: $ref" >&2
>> +fi
>> +done
>> +done
>> -- 
>> 2.11.0
>> 
>> --
>> To unsubscribe from this list: send the line "unsubscribe linux-doc" in
>> the body of a message to majord...@vger.kernel.org
>> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>> 
>
> I just did something similar, but in python (parallel even).  I like
> your version for its elegant simplicity.

Thanks. I didn't see yours. I'm fine either way although I do like
simplicity.

> I do however have a series of doc ref fixes ready to send out.  They are
> fairly fine-grained but could easily be squashed down.
>
> Given that you added this check - do you also have a patch for fixes?

None. I checked that my corner of the kernel is fine, and sent this as a
carrot for others to bite. Please go ahead with your fixes!

Thanks,
Jani.


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

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] Documentation: add script and build target to check for broken file references

[Jani Nikula]

Add a simple script and build target to do a treewide grep for
references to files under Documentation, and report the non-existing
file in stderr. It tries to take into account punctuation not part of
the filename, and wildcards, but there are bound to be false positives
too. Mostly seems accurate though.

We've moved files around enough to make having this worthwhile.

Signed-off-by: Jani Nikula <jani.nik...@intel.com>
---
 Documentation/Makefile   |  4 
 Makefile |  2 +-
 scripts/documentation-file-ref-check | 15 +++
 3 files changed, 20 insertions(+), 1 deletion(-)
 create mode 100755 scripts/documentation-file-ref-check

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 85f7856f0092..f4f5aecb81d1 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -97,6 +97,9 @@ endif # HAVE_SPHINX
 # The following targets are independent of HAVE_SPHINX, and the rules should
 # work or silently pass without Sphinx.
 
+refcheckdocs:
+   $(Q)cd $(srctree);scripts/documentation-file-ref-check
+
 cleandocs:
$(Q)rm -rf $(BUILDDIR)
$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) 
$(build)=Documentation/media clean
@@ -109,6 +112,7 @@ dochelp:
@echo  '  epubdocs- EPUB'
@echo  '  xmldocs - XML'
@echo  '  linkcheckdocs   - check for broken external links (will 
connect to external hosts)'
+   @echo  '  refcheckdocs- check for references to non-existing files 
under Documentation'
@echo  '  cleandocs   - clean all generated files'
@echo
@echo  '  make SPHINXDIRS="s1 s2" [target] Generate only docs of folder 
s1, s2'
diff --git a/Makefile b/Makefile
index cf007a31d575..a97e70a9a39c 100644
--- a/Makefile
+++ b/Makefile
@@ -1454,7 +1454,7 @@ $(help-board-dirs): help-%:
 
 # Documentation targets
 # ---
-DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs 
linkcheckdocs
+DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs 
linkcheckdocs refcheckdocs
 PHONY += $(DOC_TARGETS)
 $(DOC_TARGETS): scripts_basic FORCE
$(Q)$(MAKE) $(build)=Documentation $@
diff --git a/scripts/documentation-file-ref-check 
b/scripts/documentation-file-ref-check
new file mode 100755
index ..bc1659900e89
--- /dev/null
+++ b/scripts/documentation-file-ref-check
@@ -0,0 +1,15 @@
+#!/bin/sh
+# Treewide grep for references to files under Documentation, and report
+# non-existing files in stderr.
+
+for f in $(git ls-files); do
+   for ref in $(grep -ho "Documentation/[A-Za-z0-9_.,~/*+-]*" "$f"); do
+   # presume trailing . and , are not part of the name
+   ref=${ref%%[.,]}
+
+   # use ls to handle wildcards
+   if ! ls $ref >/dev/null 2>&1; then
+   echo "$f: $ref" >&2
+   fi
+   done
+done
-- 
2.11.0

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

Re: [PATCH 01/10] scripts: kernel-doc: get rid of unused output formats

[Jani Nikula]

On Tue, 26 Sep 2017, Mauro Carvalho Chehab <mche...@s-opensource.com> wrote:
> Since there isn't any docbook code anymore upstream,
> we can get rid of several output formats:
>
> - docbook/xml, html, html5 and list formats were used by
>   the old build system;
> - As ReST is text, there's not much sense on outputting
>   on a different text format.
>
> After this patch, only man and rst output formats are
> supported.

FWIW,

Acked-by: Jani Nikula <jani.nik...@intel.com>

Please do keep at least two output formats going forward. Otherwise the
mechanisms of having more than one output format will bitrot and get
conflated into the one output format.


>
> Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
> ---
>  scripts/kernel-doc | 1182 
> +---
>  1 file changed, 4 insertions(+), 1178 deletions(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 9d3eafea58f0..69757ee9db4c 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -51,13 +51,8 @@ The documentation comments are identified by "/**" opening 
> comment mark. See
>  Documentation/kernel-doc-nano-HOWTO.txt for the documentation comment syntax.
>  
>  Output format selection (mutually exclusive):
> -  -docbook   Output DocBook format.
> -  -html  Output HTML format.
> -  -html5 Output HTML5 format.
> -  -list  Output symbol list format. This is for use by 
> docproc.
>-man   Output troff manual page format. This is the 
> default.
>-rst   Output reStructuredText format.
> -  -text  Output plain text format.
>  
>  Output selection (mutually exclusive):
>-exportOnly output documentation for symbols that have been
> @@ -224,84 +219,11 @@ my $type_typedef = '\&(typedef\s*([_\w]+))';
>  my $type_union = '\&(union\s*([_\w]+))';
>  my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
>  my $type_fallback = '\&([_\w]+)';
> -my $type_enum_xml = '\(enum\s*([_\w]+))';
> -my $type_struct_xml = '\(struct\s*([_\w]+))';
> -my $type_typedef_xml = '\(typedef\s*([_\w]+))';
> -my $type_union_xml = '\(union\s*([_\w]+))';
> -my $type_member_xml = '\([_\w]+)(\.|-\)([_\w]+)';
> -my $type_fallback_xml = '\([_\w]+)';
>  my $type_member_func = $type_member . '\(\)';
>  
>  # Output conversion substitutions.
>  #  One for each output format
>  
> -# these work fairly well
> -my @highlights_html = (
> -   [$type_constant, "\$1"],
> -   [$type_constant2, "\$1"],
> -   [$type_func, "\$1"],
> -   [$type_enum_xml, "\$1"],
> -   [$type_struct_xml, "\$1"],
> -   [$type_typedef_xml, "\$1"],
> -   [$type_union_xml, "\$1"],
> -   [$type_env, "\$1"],
> -   [$type_param, "\$1"],
> -   [$type_member_xml, "\$1\$2\$3"],
> -   [$type_fallback_xml, "\$1"]
> -  );
> -my $local_lt = "lt:";
> -my $local_gt = "gt:";
> -my $blankline_html = $local_lt . "p" . $local_gt;# was ""
> -
> -# html version 5
> -my @highlights_html5 = (
> -[$type_constant, "\$1"],
> -[$type_constant2, " class=\"const\">\$1"],
> -[$type_func, "\$1"],
> -[$type_enum_xml, "\$1"],
> -[$type_struct_xml, " class=\"struct\">\$1"],
> -[$type_typedef_xml, " class=\"typedef\">\$1"],
> -[$type_union_xml, " class=\"union\">\$1"],
> -[$type_env, "\$1"],
> -[$type_param, "\$1]"],
> -[$type_member_xml, " class=\"struct\">\$1\$2\$3"],
> -[$type_fallback_xml, " class=\"struct\">\$1"]
> -);
> -my $blankline_html5 = $local_lt . "br /" . $local_gt;
> -
> -# XML, docbook format
> -my @highlights_xml = (
> -  ["([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2"],
> -  [$type_constant, "\$1"],
> -  [$type_consta

[PATCH] Documentation/sphinx: fix kernel-doc decode for non-utf-8 locale

[Jani Nikula]

On python3, Popen() universal_newlines=True converts the subprocess
stdout to unicode text using a codec based on user preferences. Given
LANG indicating ascii and utf-8 stdout from the subprocess, you'd get:

WARNING: kernel-doc '../scripts/kernel-doc -rst -enable-lineno
../drivers/media/dvb-core/demux.h' processing failed with: 'ascii' codec can't
decode byte 0xe2 in position 6368: ordinal not in range(128)

Fix this by dropping universal_newlines=True and replacing the implicit
LANG specific decode with an explicit utf-8 decode. This also gets rid
of the annoying conditional code for python 2 vs. 3.

Fixes: ba3501859354 ("Documentation/sphinx: fix kernel-doc extension on 
python3")
Reference: 
54c23e8e-89c0-5cea-0dcc-e938952c5642@infradead.org">http://mid.mail-archive.com/54c23e8e-89c0-5cea-0dcc-e938952c5642@infradead.org
Reported-and-tested-by: Randy Dunlap <rdun...@infradead.org>
Cc: Jonathan Corbet <cor...@lwn.net>
Cc: Mauro Carvalho Chehab <mche...@s-opensource.com>
Signed-off-by: Jani Nikula <jani.nik...@intel.com>
---
 Documentation/sphinx/kerneldoc.py | 8 +++-
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/Documentation/sphinx/kerneldoc.py 
b/Documentation/sphinx/kerneldoc.py
index d15e07f36881..39aa9e8697cc 100644
--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -27,6 +27,7 @@
 # Please make sure this works on both python2 and python3.
 #
 
+import codecs
 import os
 import subprocess
 import sys
@@ -88,13 +89,10 @@ class KernelDocDirective(Directive):
 try:
 env.app.verbose('calling kernel-doc \'%s\'' % (" ".join(cmd)))
 
-p = subprocess.Popen(cmd, stdout=subprocess.PIPE, 
stderr=subprocess.PIPE, universal_newlines=True)
+p = subprocess.Popen(cmd, stdout=subprocess.PIPE, 
stderr=subprocess.PIPE)
 out, err = p.communicate()
 
-# python2 needs conversion to unicode.
-# python3 with universal_newlines=True returns strings.
-if sys.version_info.major < 3:
-out, err = unicode(out, 'utf-8'), unicode(err, 'utf-8')
+out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8')
 
 if p.returncode != 0:
 sys.stderr.write(err)
-- 
2.11.0

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

Re: [PATCH 1/2] docs: kernel-doc comments are ASCII

[Jani Nikula]

On Thu, 31 Aug 2017, Randy Dunlap <rdun...@infradead.org> wrote:
> On 08/31/17 09:36, Jani Nikula wrote:
>> On Thu, 31 Aug 2017, Jani Nikula <jani.nik...@linux.intel.com> wrote:
>>> On Thu, 31 Aug 2017, Randy Dunlap <rdun...@infradead.org> wrote:
>>>> On 08/31/17 07:17, Jonathan Corbet wrote:
>>>>> On Thu, 31 Aug 2017 10:56:26 -0300
>>>>> Mauro Carvalho Chehab <mche...@s-opensource.com> wrote:
>>>>>
>>>>>> It should have something to do with python version and/or to some
>>>>>> locale info at the system, as neither I or Jon can reproduce it.
>>>>>
>>>>> I can't reproduce it here, but I have certainly seen situations where
>>>>> Python 2 wants to run with the ascii codec by default.
>>>>>
>>>>> Note that the exception happens in our Sphinx extension, not in Sphinx
>>>>> itself.  We've had other non-ascii text in our docs, so I think Sphinx is
>>>>> doing the right thing.  The problem is with our own code.  If I could
>>>>> reproduce it, it shouldn't be too hard to track down - take out that
>>>>> massive "except anything" block and see where it explodes.
>>>>>
>>>>> Randy, which distribution are you running, and are you using their version
>>>>> of Sphinx?
>>>>
>>>> opensuse LEAP 42.2
>>>> Yes, their sphinx 1.3.1.
>>>
>>> What's your LANG setting? I think that's what it boils down to, and
>>> trying to work around non-UTF-8 LANG in both python 2 and 3 compatible
>>> ways.
>>>
>>> The odd thing is that I can reproduce the issue using a small python
>>> snippet, but not through Sphinx.
>> 
>> Your original error message suggests your Sphinx actually uses python
>> 3. Can you check that? The clue is that it's the *decode* that fails.
>
> Where do you see that clue?

The message, "'ascii' codec can't decode byte 0xe2 in position 6368:
ordinal not in range(128)". In my testing I could only get that *decode*
error message using python 3.

> My /usr/bin/python is linked to python2.7:
>
>> ll /usr/bin/python
> lrwxrwxrwx 1 root root 9 Jun 10 19:59 /usr/bin/python -> python2.7*

Sure, but how about 'head $(which sphinx-build)'?

I could be completely mistaken too. ;)

>> Does the below patch help? It avoids the implicit ascii decoding due to
>> universal_newlines=True and your LANG setting, and does explicit utf-8
>> decoding instead.
>> 
>> Fingers crossed.
>
> testing now.

Thanks.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] docs: kernel-doc comments are ASCII

[Jani Nikula]

On Thu, 31 Aug 2017, Jani Nikula <jani.nik...@linux.intel.com> wrote:
> On Thu, 31 Aug 2017, Randy Dunlap <rdun...@infradead.org> wrote:
>> On 08/31/17 07:17, Jonathan Corbet wrote:
>>> On Thu, 31 Aug 2017 10:56:26 -0300
>>> Mauro Carvalho Chehab <mche...@s-opensource.com> wrote:
>>> 
>>>> It should have something to do with python version and/or to some
>>>> locale info at the system, as neither I or Jon can reproduce it.
>>> 
>>> I can't reproduce it here, but I have certainly seen situations where
>>> Python 2 wants to run with the ascii codec by default.
>>> 
>>> Note that the exception happens in our Sphinx extension, not in Sphinx
>>> itself.  We've had other non-ascii text in our docs, so I think Sphinx is
>>> doing the right thing.  The problem is with our own code.  If I could
>>> reproduce it, it shouldn't be too hard to track down - take out that
>>> massive "except anything" block and see where it explodes.
>>> 
>>> Randy, which distribution are you running, and are you using their version
>>> of Sphinx?
>>
>> opensuse LEAP 42.2
>> Yes, their sphinx 1.3.1.
>
> What's your LANG setting? I think that's what it boils down to, and
> trying to work around non-UTF-8 LANG in both python 2 and 3 compatible
> ways.
>
> The odd thing is that I can reproduce the issue using a small python
> snippet, but not through Sphinx.

Your original error message suggests your Sphinx actually uses python
3. Can you check that? The clue is that it's the *decode* that fails.

Does the below patch help? It avoids the implicit ascii decoding due to
universal_newlines=True and your LANG setting, and does explicit utf-8
decoding instead.

Fingers crossed.

BR,
Jani.


diff --git a/Documentation/sphinx/kerneldoc.py 
b/Documentation/sphinx/kerneldoc.py
index d15e07f36881..39aa9e8697cc 100644
--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -27,6 +27,7 @@
 # Please make sure this works on both python2 and python3.
 #
 
+import codecs
 import os
 import subprocess
 import sys
@@ -88,13 +89,10 @@ class KernelDocDirective(Directive):
 try:
 env.app.verbose('calling kernel-doc \'%s\'' % (" ".join(cmd)))
 
-p = subprocess.Popen(cmd, stdout=subprocess.PIPE, 
stderr=subprocess.PIPE, universal_newlines=True)
+p = subprocess.Popen(cmd, stdout=subprocess.PIPE, 
stderr=subprocess.PIPE)
 out, err = p.communicate()
 
-# python2 needs conversion to unicode.
-# python3 with universal_newlines=True returns strings.
-if sys.version_info.major < 3:
-out, err = unicode(out, 'utf-8'), unicode(err, 'utf-8')
+out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8')
 
 if p.returncode != 0:
 sys.stderr.write(err)



-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] docs: kernel-doc comments are ASCII

[Jani Nikula]

On Thu, 31 Aug 2017, Randy Dunlap <rdun...@infradead.org> wrote:
> On 08/31/17 07:17, Jonathan Corbet wrote:
>> On Thu, 31 Aug 2017 10:56:26 -0300
>> Mauro Carvalho Chehab <mche...@s-opensource.com> wrote:
>> 
>>> It should have something to do with python version and/or to some
>>> locale info at the system, as neither I or Jon can reproduce it.
>> 
>> I can't reproduce it here, but I have certainly seen situations where
>> Python 2 wants to run with the ascii codec by default.
>> 
>> Note that the exception happens in our Sphinx extension, not in Sphinx
>> itself.  We've had other non-ascii text in our docs, so I think Sphinx is
>> doing the right thing.  The problem is with our own code.  If I could
>> reproduce it, it shouldn't be too hard to track down - take out that
>> massive "except anything" block and see where it explodes.
>> 
>> Randy, which distribution are you running, and are you using their version
>> of Sphinx?
>
> opensuse LEAP 42.2
> Yes, their sphinx 1.3.1.

What's your LANG setting? I think that's what it boils down to, and
trying to work around non-UTF-8 LANG in both python 2 and 3 compatible
ways.

The odd thing is that I can reproduce the issue using a small python
snippet, but not through Sphinx.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] docs: kernel-doc comments are ASCII

[Jani Nikula]

On Thu, 31 Aug 2017, Mauro Carvalho Chehab <mche...@s-opensource.com> wrote:
> As Documentation/conf.py has:
>
>   # -*- coding: utf-8 -*-
>
> on its first line, I suspect that the error you're getting is likely
> due to the usage of a python version that doesn't recognize this.

AFAIK that has nothing to do with python I/O, and everything to do with
the encoding of that specific python source file.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation: small fixes for LEDs, hide notes about vibration

[Jani Nikula]

On Tue, 29 Aug 2017, Pavel Machek <pa...@ucw.cz> wrote:
> Hi!
>
>> > -As a specific example of this use-case, let's look at vibrate feature on
>> > -phones. Vibrate function on phones is implemented using PWM pins on SoC or
>> > -PMIC. There is a need to activate one shot timer to control the vibrate
>> > -feature, to prevent user space crashes leaving the phone in vibrate mode
>> > -permanently causing the battery to drain.
>> 
>> I'm not sure if it is a good idea to remove this description. Users will
>> still be able to use transient trigger this way. It has been around for
>> five years already and there are users which employ it in this
>> particular way [0].
>
> I am. Yes, people were doing that, but no, vibration motor is not a
> LED. PWM behaviour is different, for example, motor is likely to stop
> at low PWM values. We do not want people to do that.
>
>> Apart from that it's the only documented kernel API for vibrate devices
>> AFAICT.
>
> Input subsystem has force-feedback protocol, which is very often just
> vibrations. Documentation/input/ff.rst . Nokia N900 phone actually
> uses that API.

N900 as shipped by Nokia used an ad hoc sysfs interface. Because that
sucked, I advocated using the force feedback API for N950 and
N9. Because what is vibration but force feedback? It's a much more
versatile API for vibration than a simple trigger. You get to upload
effects and have the kernel play them for you, also stopping them in a
timely manner regardless of the userspace dying and whatnot. I didn't
double check now, but IIRC you could also link the input to force
feedback, e.g. for touch vibrations.


BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH V3 2/8] drivers: boot_constraint: Add boot_constraints_disable kernel parameter

[Jani Nikula]

On Tue, 29 Aug 2017, Greg Kroah-Hartman <gre...@linuxfoundation.org> wrote:
> On Tue, Aug 01, 2017 at 02:53:43PM +0530, Viresh Kumar wrote:
>> Users must be given an option to discard any constraints set by
>> bootloaders. For example, consider that a constraint is set for the LCD
>> controller's supply and the LCD driver isn't loaded by the kernel. If
>> the user doesn't need to use the LCD device, then he shouldn't be forced
>> to honour the constraint.
>> 
>> We can also think about finer control of such constraints with help of
>> some sysfs files, but a kernel parameter is fine to begin with.
>> 
>> Tested-by: Rajendra Nayak <rna...@codeaurora.org>
>> Signed-off-by: Viresh Kumar <viresh.ku...@linaro.org>
>> ---
>>  Documentation/admin-guide/kernel-parameters.txt |  3 +++
>>  drivers/base/boot_constraints/core.c| 17 +
>>  2 files changed, 20 insertions(+)
>> 
>> diff --git a/Documentation/admin-guide/kernel-parameters.txt 
>> b/Documentation/admin-guide/kernel-parameters.txt
>> index d9c171ce4190..0706d1b6004d 100644
>> --- a/Documentation/admin-guide/kernel-parameters.txt
>> +++ b/Documentation/admin-guide/kernel-parameters.txt
>> @@ -426,6 +426,9 @@
>>  embedded devices based on command line input.
>>  See Documentation/block/cmdline-partition.txt
>>  
>> +boot_constraints_disable
>> +Do not set any boot constraints for devices.
>
> Shouldn't that be the default?  As really, that is what the situation is
> today, why force everyone to always enable the disable value?  And
> enabling a value to disable something is usually a sign of bad naming...
>
>> +
>>  boot_delay= Milliseconds to delay each printk during boot.
>>  Values larger than 10 seconds (1) are changed to
>>  no delay (0).
>> diff --git a/drivers/base/boot_constraints/core.c 
>> b/drivers/base/boot_constraints/core.c
>> index 366a05d6d9ba..e0c33b2b216f 100644
>> --- a/drivers/base/boot_constraints/core.c
>> +++ b/drivers/base/boot_constraints/core.c
>> @@ -24,6 +24,17 @@
>>  static LIST_HEAD(constraint_devices);
>>  static DEFINE_MUTEX(constraint_devices_mutex);
>>  
>> +static bool boot_constraints_disabled;
>
> Again, this should only be an "enable" type of option, that kicks in if
> you are using this type of bootloader/kernel interaction.  Don't force
> someone to disable it.

I might add that "disable" type options lead to annoying double
negatives. Regardless of the default, I'd generally prefer "enable" type
options that you enable/disable as needed.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Jani Nikula]

On Fri, 25 Aug 2017, Josh Holland <anowlcalledj...@gmail.com> wrote:
> On 2017-08-24, Jani Nikula wrote:
>> On Wed, 23 Aug 2017, Josh Holland <anowlcalledj...@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 <anowlcalledj...@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 majord...@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Jani Nikula]

On Wed, 23 Aug 2017, Josh Holland <anowlcalledj...@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 <anowlcalledj...@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
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: docs build questions

[Jani Nikula]

On Mon, 14 Aug 2017, Randy Dunlap <rdun...@infradead.org> wrote:
> On 08/13/2017 11:46 PM, Markus Heiser wrote:
>> Hi Randy,
>> 
>>> Am 13.08.2017 um 19:29 schrieb Randy Dunlap <rdun...@infradead.org>:
>>> Lots of ERRORs where a doc comment is of the form GPP_ (ending with a '_'):
>>>
>>> ../block/bio.c:404: ERROR: Unknown target name: "gfp".
>> 
>> Yes, this is a conflict since comments are reST Markup.
>> 
>>  https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html
>> 
>> In sources we like to use FOO_ (ending with a '_'), which is a
>> hyperlink markup in reST:
>> 
>>  http://www.sphinx-doc.org/en/stable/rest.html#hyperlinks
>> 
>> The only solution I see is to replace FOO_ with ``FOO_``
>
> I guess that's OK in doc files, but most of these comments are in source files
> and requiring ``xyz_`` there is not nice.

I assume very few actual symbols end in underscore, and this is more of
a question of referencing a group of FOO_ prefixed symbols. In these
cases, I prefer using FOO_* as it both avoids the problem and makes
perfect sense in plain text.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: docs build questions

[Jani Nikula]

On Mon, 14 Aug 2017, Markus Heiser <markus.hei...@darmarit.de> wrote:
> see "Sphinx Install" Documentation/doc-guide/sphinx.rst (ATM in Jon's 
> docs-next)
>
>  The ReST markups currently used by the Documentation/ files are meant to be
>  built with ``Sphinx`` version 1.3 or upper. If you're desiring to build
>  PDF outputs, it is recommended to use version 1.4.6 or upper.
>
> Sorry for the mess in the past. Mauro has now cleared this up for us /
> thanks Mauro

If you require a specific Sphinx version or higher, the thing to do is
specify needs_sphinx in conf.py so that Sphinx gives you a proper error
message:

"""
Sphinx version error:
This project needs at least Sphinx v1.3 and therefore cannot be built with this 
version.
"""

It's a bit clunky, but you could even specify -Dneeds_sphinx=1.4 from
the Makefile for the PDF build, to have different requirements for
different builders. AFAICT you can't get at the builder directly from
conf.py.


BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH 0/4] Documentation: generated module param documentation

[Jani Nikula]

On Mon, 24 Jul 2017, Jonathan Corbet <cor...@lwn.net> wrote:
> On Wed, 19 Jul 2017 16:05:01 +0300
> Jani Nikula <jani.nik...@intel.com> wrote:
>
>> Hi Jon, all, here are some quick'n'dirty patches to semi-automatically
>> generate module param documentation from the source, via module build
>> and modinfo(8). No polish or proper design, just a hacked up
>> proof-of-concept to think about.
>> 
>> Do we want nice documentation for module parameters, somewhere that
>> search engines can find them? And do we want to reuse the documentation
>> already in place for parameters?
>
> Certainly I like the idea of automatically generating module parameter
> docs.  I will confess that I don't like committing a duplicated version
> of those docs into the repository, though; nobody will ever update them
> until somebody complains.  I'm also concerned about removing
> documentation from kernel-parameters.rst, since that's where people tend
> to go looking for such information now.
>
> I wonder if we could hack up some sort of trick using "cc -E" and a
> special include file to extract the info from the source?  Then maybe a
> simple module-doc extension to run that trick and include the results?
> It means adding a little stanza for each module we want to document, but
> I'm not convinced that's worse than committing the documentation
> separately.
>
> Thoughts?

Just a quick reply that one alternative I came up with afterwards is
doing what I do here, but with a separate "module param docs" target
that does allmodconfig, build, and modinfo on all the .ko. Likely slow
as molasses, but bypasses committing intermediate files and doesn't slow
down the main docs build.

I'll have to think about your proposal a bit more.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[RFC PATCH 1/4] scripts: add modinfo-to-rst script to extract module parameters

[Jani Nikula]

Add a simple script to extract module param info from .ko using
modinfo(8), and convert the results to rst. There's no filtering of rst
special characters or anything.

Signed-off-by: Jani Nikula <jani.nik...@intel.com>
---
 scripts/modinfo-to-rst | 24 
 1 file changed, 24 insertions(+)
 create mode 100755 scripts/modinfo-to-rst

diff --git a/scripts/modinfo-to-rst b/scripts/modinfo-to-rst
new file mode 100755
index ..e415c68db72e
--- /dev/null
+++ b/scripts/modinfo-to-rst
@@ -0,0 +1,24 @@
+#!/bin/bash
+# usage: modinfo-to-rst /path/to/module.ko
+
+SELF=modinfo-to-rst
+MODINFO=/sbin/modinfo
+
+if [[ "$#" != "1" ]]; then
+   echo "$SELF: usage: $SELF (modulename|filename)" >&2
+   exit 1
+fi
+
+MODULE="$1"
+MODULENAME="$(basename -s .ko $MODULE)"
+
+cat <http://vger.kernel.org/majordomo-info.html

[RFC PATCH 0/4] Documentation: generated module param documentation

[Jani Nikula]

Hi Jon, all, here are some quick'n'dirty patches to semi-automatically
generate module param documentation from the source, via module build
and modinfo(8). No polish or proper design, just a hacked up
proof-of-concept to think about.

Do we want nice documentation for module parameters, somewhere that
search engines can find them? And do we want to reuse the documentation
already in place for parameters?


BR,
Jani.

Jani Nikula (4):
  scripts: add modinfo-to-rst script to extract module parameters
  Documentation: start module parameter documentation autogenerated from
modinfo
  Documentation: add drm and drm_kms_helper module param documentation
  scripts: add modparams-docs-update script to update all module
parameter docs

 Documentation/admin-guide/kernel-parameters.rst|   8 ++
 Documentation/admin-guide/kernel-parameters.txt|  32 --
 Documentation/admin-guide/module-parameters/README |  14 +++
 .../admin-guide/module-parameters/drm.rst  |  26 +
 .../module-parameters/drm_kms_helper.rst   |  23 
 .../admin-guide/module-parameters/i915.rst | 125 +
 scripts/modinfo-to-rst |  24 
 scripts/modparams-docs-update  |  20 
 8 files changed, 240 insertions(+), 32 deletions(-)
 create mode 100644 Documentation/admin-guide/module-parameters/README
 create mode 100644 Documentation/admin-guide/module-parameters/drm.rst
 create mode 100644 
Documentation/admin-guide/module-parameters/drm_kms_helper.rst
 create mode 100644 Documentation/admin-guide/module-parameters/i915.rst
 create mode 100755 scripts/modinfo-to-rst
 create mode 100755 scripts/modparams-docs-update

-- 
2.11.0

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

[RFC PATCH 2/4] Documentation: start module parameter documentation autogenerated from modinfo

[Jani Nikula]

Module parameters are supposed to be documented using MODULE_PARM_DESC
in source. We should be able to use this information to autogenerate
module parameter documentation instead of duplicating that information
manually in kernel-parameters.rst.

Parsing that information directly from the source is hard. It's not
obvious what the module name is when you encounter MODULE_PARM_DESC. The
information may be entered in source using several layers of other
macros. Oh, and you'd need another C parser.

An alternative is to use modinfo(8) on the compiled kernel modules. The
trouble is, you have to actually build the module to do so, and that is
obviously too slow for the documentation build.

Here's an approach to commit the generated information in the repo. It's
not ideal to commit generated data, but at least the information can be
automatically updated as needed.

All the generated files are included as a toctree in
kernel-parameters.rst.

Signed-off-by: Jani Nikula <jani.nik...@intel.com>
---
 Documentation/admin-guide/kernel-parameters.rst|   8 ++
 Documentation/admin-guide/kernel-parameters.txt|  14 ---
 Documentation/admin-guide/module-parameters/README |  10 ++
 .../admin-guide/module-parameters/i915.rst | 125 +
 4 files changed, 143 insertions(+), 14 deletions(-)
 create mode 100644 Documentation/admin-guide/module-parameters/README
 create mode 100644 Documentation/admin-guide/module-parameters/i915.rst

diff --git a/Documentation/admin-guide/kernel-parameters.rst 
b/Documentation/admin-guide/kernel-parameters.rst
index d76ab3907e2b..eed98e70b700 100644
--- a/Documentation/admin-guide/kernel-parameters.rst
+++ b/Documentation/admin-guide/kernel-parameters.rst
@@ -204,6 +204,14 @@ bytes respectively. Such letter suffixes can also be 
entirely omitted:
 .. include:: kernel-parameters.txt
:literal:
 
+Module parameters
+-
+
+.. toctree::
+   :glob:
+
+   module-parameters/*
+
 Todo
 
 
diff --git a/Documentation/admin-guide/kernel-parameters.txt 
b/Documentation/admin-guide/kernel-parameters.txt
index d9c171ce4190..4e731b44db95 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -1382,20 +1382,6 @@
i8k.restricted  [HW] Allow controlling fans only if SYS_ADMIN
capability is set.
 
-   i915.invert_brightness=
-   [DRM] Invert the sense of the variable that is used to
-   set the brightness of the panel backlight. Normally a
-   brightness value of 0 indicates backlight switched off,
-   and the maximum of the brightness value sets the 
backlight
-   to maximum brightness. If this parameter is set to 0
-   (default) and the machine requires it, or this parameter
-   is set to 1, a brightness value of 0 sets the backlight
-   to maximum brightness, and the maximum of the brightness
-   value switches the backlight off.
-   -1 -- never invert brightness
-0 -- machine default
-1 -- force brightness inversion
-
icn=[HW,ISDN]
Format: [,[,[,]]]
 
diff --git a/Documentation/admin-guide/module-parameters/README 
b/Documentation/admin-guide/module-parameters/README
new file mode 100644
index ..38e34f83bdc7
--- /dev/null
+++ b/Documentation/admin-guide/module-parameters/README
@@ -0,0 +1,10 @@
+The files in this directory are automatically generated. Please don't update
+them manually.
+
+To add a new file, run:
+
+   $ scripts/modinfo-to-rst path/to/module.ko > \
+ Documentation/admin-guide/module-parameters/module.rst
+
+Make sure you do this with a recently built module.ko! Review and commit the
+changes afterwards.
diff --git a/Documentation/admin-guide/module-parameters/i915.rst 
b/Documentation/admin-guide/module-parameters/i915.rst
new file mode 100644
index ..7dd4a92fe7b0
--- /dev/null
+++ b/Documentation/admin-guide/module-parameters/i915.rst
@@ -0,0 +1,125 @@
+.. Autogenerated from i915.ko using modinfo(8) and modinfo-to-rst
+
+i915
+
+
+alpha_support (bool)
+  Enable alpha quality driver support for latest hardware. See also 
CONFIG_DRM_I915_ALPHA_SUPPORT.
+
+disable_display (bool)
+  Disable display (default: false)
+
+disable_power_well (int)
+  Disable display power wells when possible (-1=auto [default], 0=power wells 
always on, 1=power wells disabled when possible)
+
+edp_vswing (int)
+  Ignore/Override vswing pre-emph table selection from VBT (0=use value from 
vbt [default], 1=low power swing(200mV),2=default swing(400mV))
+
+enable_cmd_parser (bool)
+  Enable command parsing (true=enabled [default], false=disabled)
+
+enable_dbc (bool)
+  Enable support for dynamic backlight control (default:true)
+
+

[RFC PATCH 3/4] Documentation: add drm and drm_kms_helper module param documentation

[Jani Nikula]

Obviously the MODULE_PARM_DESC documentation for
drm_kms_helper.edid_firmware needs some updating before we could
consider this.

Signed-off-by: Jani Nikula <jani.nik...@intel.com>
---
 Documentation/admin-guide/kernel-parameters.txt| 18 ---
 .../admin-guide/module-parameters/drm.rst  | 26 ++
 .../module-parameters/drm_kms_helper.rst   | 23 +++
 3 files changed, 49 insertions(+), 18 deletions(-)
 create mode 100644 Documentation/admin-guide/module-parameters/drm.rst
 create mode 100644 
Documentation/admin-guide/module-parameters/drm_kms_helper.rst

diff --git a/Documentation/admin-guide/kernel-parameters.txt 
b/Documentation/admin-guide/kernel-parameters.txt
index 4e731b44db95..f0cee38beef2 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -854,24 +854,6 @@
The filter can be disabled or changed to another
driver later using sysfs.
 
-   drm_kms_helper.edid_firmware=[:][,[:]]
-   Broken monitors, graphic adapters, KVMs and EDIDless
-   panels may send no or incorrect EDID data sets.
-   This parameter allows to specify an EDID data sets
-   in the /lib/firmware directory that are used instead.
-   Generic built-in EDID data sets are used, if one of
-   edid/1024x768.bin, edid/1280x1024.bin,
-   edid/1680x1050.bin, or edid/1920x1080.bin is given
-   and no file with the same name exists. Details and
-   instructions how to build your own EDID data are
-   available in Documentation/EDID/HOWTO.txt. An EDID
-   data set will only be used for a particular connector,
-   if its name and a colon are prepended to the EDID
-   name. Each connector may use a unique EDID data
-   set by separating the files with a comma.  An EDID
-   data set with no connector name will be used for
-   any connectors not explicitly specified.
-
dscc4.setup=[NET]
 
dt_cpu_ftrs=[PPC]
diff --git a/Documentation/admin-guide/module-parameters/drm.rst 
b/Documentation/admin-guide/module-parameters/drm.rst
new file mode 100644
index ..8b03a54f844c
--- /dev/null
+++ b/Documentation/admin-guide/module-parameters/drm.rst
@@ -0,0 +1,26 @@
+.. Autogenerated from drm.ko using modinfo(8) and modinfo-to-rst
+
+drm
+===
+
+debug (int)
+  Enable debug output, where each bit enables a debug category.
+   Bit 0 (0x01) will enable CORE messages (drm core code)
+   Bit 1 (0x02) will enable DRIVER messages (drm controller code)
+   Bit 2 (0x04) will enable KMS messages (modesetting code)
+   Bit 3 (0x08) will enable PRIME messages (prime code)
+   Bit 4 (0x10) will enable ATOMIC messages (atomic code)
+   Bit 5 (0x20) will enable VBL messages (vblank code)
+
+edid_fixup (int)
+  Minimum number of valid EDID header bytes (0-8, default 6)
+
+timestamp_monotonic (int)
+  Use monotonic timestamps
+
+timestamp_precision_usec (int)
+  Max. error on timestamps [usecs]
+
+vblankoffdelay (int)
+  Delay until vblank irq auto-disable [msecs] (0: never disable, <0: disable 
immediately)
+
diff --git a/Documentation/admin-guide/module-parameters/drm_kms_helper.rst 
b/Documentation/admin-guide/module-parameters/drm_kms_helper.rst
new file mode 100644
index ..8940951d75da
--- /dev/null
+++ b/Documentation/admin-guide/module-parameters/drm_kms_helper.rst
@@ -0,0 +1,23 @@
+.. Autogenerated from drm_kms_helper.ko using modinfo(8) and modinfo-to-rst
+
+drm_kms_helper
+==
+
+dp_aux_i2c_speed_khz (int)
+  Assumed speed of the i2c bus in kHz, (1-400, default 10)
+
+dp_aux_i2c_transfer_size (int)
+  Number of bytes to transfer in a single I2C over DP AUX CH message, (1-16, 
default 16)
+
+drm_fbdev_overalloc (int)
+  Overallocation of the fbdev buffer (%) [default=100]
+
+edid_firmware (string)
+  Do not probe monitor, use specified EDID blob from built-in data or 
/lib/firmware instead. 
+
+fbdev_emulation (bool)
+  Enable legacy fbdev emulation [default=true]
+
+poll (bool)
+  
+
-- 
2.11.0

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

Re: [PATCH] Make the main documentation title less Geocities

[Jani Nikula]

On Tue, 06 Jun 2017, Konstantin Ryabitsev <konstan...@linuxfoundation.org> 
wrote:
> This is probably the lamest patch ever, but then again "Welcome to The
> Linux Kernel's documentation" is nearly equally lame. Really, we don't
> need to "Welcome" people to the documentation, just tell them what the
> site is about.

The original index.rst including the lame title was autogenerated by
'sphinx-quickstart' and I failed to make it less lame. Thanks for fixing
this.

Acked-by: Jani Nikula <jani.nik...@intel.com>

>
> Signed-off-by: Konstantin Ryabitsev <konstan...@linuxfoundation.org>
> ---
>  Documentation/index.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index bc67dbf..0536b3f 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -3,8 +3,8 @@
> You can adapt this file completely to your liking, but it should at least
> contain the root `toctree` directive.
>  
> -Welcome to The Linux Kernel's documentation
> -===
> +The Linux Kernel documentation
> +==
>  
>  This is the top level of the kernel's documentation tree.  Kernel
>  documentation, like the kernel itself, is very much a work in progress;

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/3] Documentation: Move visorbus documentation from staging to Documentation/

[Jani Nikula]

On Mon, 05 Jun 2017, David Kershner <david.kersh...@unisys.com> wrote:
> This patch simply does a git mv of the
> drivers/staging/unisys/Documentation directory to Documentation.

Up to Jon, of course, but I wouldn't add any new files directly under
Documentation, and especially not something as specific as this.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/8] i2c: refactor core and break out blocks

[Jani Nikula]

On Fri, 26 May 2017, Wolfram Sang <w...@the-dreams.de> wrote:
> Yes, I wanted to do this for years now... The I2C core became a huge 
> monolithic
> blob getting harder and harder to maintain. This series breaks out some
> functional parts into seperate files. This makes the code easier to handle
> because of the smaller chunks. It reduces ifdeffery because we can now handle
> compilation at the Makefile level. And it helps to spread responsibility, e.g.
> the ACPI maintainers do now have a dedicated file listed in MAINTAINERS.
>
> This series was tested with a Renesas Lager board (R-Car H2 SoC). It booted
> normally and all device drivers for I2C clients seem to work normally. I wired
> two I2C busses together and used i2c-slave-eeprom to let one I2C IP core read
> out data from the other. That all worked fine. Buildbot is also happy, it 
> found
> two issues of the first (non public) iteration. Thanks!
>
> I did not test ACPI and hope for some assistance here :) I'd also be happy if
> people could check the includes of the newly created files, there might be
> missing some.

If you don't mind sending the whole series to the intel-gfx list (Cc'd),
our CI will run a bunch of tests on it, exercising our use of the I2C
adapter interfaces for display data channel and I2C over Display Port
native aux.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

[Jani Nikula]

On Mon, 15 May 2017, Peter Zijlstra <pet...@infradead.org> wrote:
> On Mon, May 15, 2017 at 01:29:58PM +0300, Jani Nikula wrote:
>> On Mon, 15 May 2017, Peter Zijlstra <pet...@infradead.org> wrote:
>> > The intention is to aid readability. Making comments worse so that some
>> > retarded script can generate better html or whatnot is just that,
>> > retarded.
>> >
>> > Code matters, generated documentation not so much. I'll take a comment
>> > that reads well over one that generates pretty html any day.
>> 
>> The deal is that if you start your comments with "/**" they'll be
>> processed with the retarded script to produce pretty html.
>> 
>> For the most part the comments that generate pretty html also read well,
>> and we don't expect or want anyone to go overboard with markup. I don't
>> think it's unreasonable to make small concessions to improve generated
>> documentation for people who care about it even if you don't.
>
> No. Such a concession has pure negative value. It opens the door to more
> patches converting this or that comment to be prettier or whatnot. And
> before you know it there's a Markus like idiot spamming you with dozens
> of crap patches to prettify the generated crud.
>
> Not to mention that this would mean having to learn this rest crud in
> order to write these comments.
>
> All things I'm not prepared to do.
>
> I'm all for useful comments, but I see no value _at_all_ in this
> generated nonsense. The only reason I sometimes use the docbook comment
> style is because its fairly uniform and the build bot gets you a warning
> when your function signature no longer matches with the comment. But
> if you make this painful I'll simply stop using them.

I see plenty of value in the generated documentation, but I see zero
return on investment in spending any time trying to convince you about
any of it.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

[Jani Nikula]

On Mon, 15 May 2017, Peter Zijlstra <pet...@infradead.org> wrote:
> The intention is to aid readability. Making comments worse so that some
> retarded script can generate better html or whatnot is just that,
> retarded.
>
> Code matters, generated documentation not so much. I'll take a comment
> that reads well over one that generates pretty html any day.

The deal is that if you start your comments with "/**" they'll be
processed with the retarded script to produce pretty html.

For the most part the comments that generate pretty html also read well,
and we don't expect or want anyone to go overboard with markup. I don't
think it's unreasonable to make small concessions to improve generated
documentation for people who care about it even if you don't.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Missing File REPORTING-BUGS In Linux Kernel.

[Jani Nikula]

On Mon, 08 May 2017, Randy Dunlap <rdun...@infradead.org> wrote:
> On 05/08/17 05:30, Keith Christian wrote:
>> Is there a link to the discussion for changing to .rst?
>
> I don't recall much discussion.  There may have been some on the
> linux-doc mailing list.

There was "some discussion" that dragged on for the better part of a
year. It spanned more threads than I care to remember. Indeed I wish I
could forget. Perhaps you already did. ;)

These articles provide some background:

https://lwn.net/Articles/671496/
https://lwn.net/Articles/692704/
https://lwn.net/Articles/692705/

> As with many things that are kernel-related, it depends a lot on who
> is doing the work and their choices and decisions.

I seem to recall there were a lot of opinions from people who couldn't
care less about documentation too. ;)

>> There is a convention for keeping essential documentation in a simple
>> format that can be read without additional processing.  Where are we
>> going with this?
>
> .rst files are still readable with an editor or 'more' etc.

Moreover, we're converting all of the DocBook XML documentation over to
rst too, making much more documentation human readable (and writable)
without additional processing.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH V2] docs: process/4.Coding.rst: Fix a couple of document refs

[Jani Nikula]

On Thu, 20 Apr 2017, Andrew Clayton <and...@digital-domain.net> wrote:
> In Documentation/process/4.Coding.rst there were a couple of paragraphs
> that spilled over the 80 character line length. This was likely caused
> when the document was converted to reStructuredText. Re-flow the
> paragraphs and make the document references proper reStructuredText
> :ref: links.
>
> This also adds the appropriate reStructuredText file heading to
> kernel-parameters.rst as referenced by the kernel-parameters link in
> this patch.
>
> Signed-off-by: Andrew Clayton <and...@digital-domain.net>
> ---
>  V2 - Convert the document references into :ref: links

Thanks, this seems like a much better change to me.

Reviewed-by: Jani Nikula <jani.nik...@intel.com>

Jon, Mauro, am I right in that the only place that actually leads to the
development process documentation that starts at 1.Intro.rst is in fact
submitting-patches.rst? It's not referenced in any indexes is it?

BR,
Jani.


>  
>  Documentation/admin-guide/kernel-parameters.rst |  2 ++
>  Documentation/process/4.Coding.rst  | 17 +
>  2 files changed, 11 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/admin-guide/kernel-parameters.rst 
> b/Documentation/admin-guide/kernel-parameters.rst
> index b516164999a8..e41d90dbd6c8 100644
> --- a/Documentation/admin-guide/kernel-parameters.rst
> +++ b/Documentation/admin-guide/kernel-parameters.rst
> @@ -1,3 +1,5 @@
> +.. _kernelparameters:
> +
>  The kernel's command-line parameters
>  
>  
> diff --git a/Documentation/process/4.Coding.rst 
> b/Documentation/process/4.Coding.rst
> index 2a728d898fc5..6df19943dd4d 100644
> --- a/Documentation/process/4.Coding.rst
> +++ b/Documentation/process/4.Coding.rst
> @@ -22,11 +22,11 @@ Coding style
>  
>  
>  The kernel has long had a standard coding style, described in
> -Documentation/process/coding-style.rst.  For much of that time, the policies 
> described
> -in that file were taken as being, at most, advisory.  As a result, there is
> -a substantial amount of code in the kernel which does not meet the coding
> -style guidelines.  The presence of that code leads to two independent
> -hazards for kernel developers.
> +:ref:`Documentation/process/coding-style.rst `.  For much of
> +that time, the policies described in that file were taken as being, at most,
> +advisory.  As a result, there is a substantial amount of code in the kernel
> +which does not meet the coding style guidelines.  The presence of that code
> +leads to two independent hazards for kernel developers.
>  
>  The first of these is to believe that the kernel coding standards do not
>  matter and are not enforced.  The truth of the matter is that adding new
> @@ -343,9 +343,10 @@ user-space developers to know what they are working 
> with.  See
>  Documentation/ABI/README for a description of how this documentation should
>  be formatted and what information needs to be provided.
>  
> -The file Documentation/admin-guide/kernel-parameters.rst describes all of 
> the kernel's
> -boot-time parameters.  Any patch which adds new parameters should add the
> -appropriate entries to this file.
> +The file :ref:`Documentation/admin-guide/kernel-parameters.rst
> +` describes all of the kernel's boot-time parameters.
> +Any patch which adds new parameters should add the appropriate entries to
> +this file.
>  
>  Any new configuration options must be accompanied by help text which
>  clearly explains the options and when the user might want to select them.

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] docs: process/4.Coding.rst: Re-flow a couple of paragraphs

[Jani Nikula]

On Wed, 19 Apr 2017, Andrew Clayton <and...@digital-domain.net> wrote:
> In Documentation/process/4.Coding.rst there were a couple of paragraphs
> that spilled over the 80 character line length.
>
> This brings them back in line with the rest of the document.
>
> Signed-off-by: Andrew Clayton <and...@digital-domain.net>

While this change is technically fine, fixing an issue likely introduced
by changing the filenames using sed, I think the right thing to do would
be to cross-reference the documents using reStructuredText constructs
rather than just naming files inline.

BR,
Jani.


> ---
>  Documentation/process/4.Coding.rst | 14 +++---
>  1 file changed, 7 insertions(+), 7 deletions(-)
>
> diff --git a/Documentation/process/4.Coding.rst 
> b/Documentation/process/4.Coding.rst
> index 2a728d898fc5..017f22fa970c 100644
> --- a/Documentation/process/4.Coding.rst
> +++ b/Documentation/process/4.Coding.rst
> @@ -22,10 +22,10 @@ Coding style
>  
>  
>  The kernel has long had a standard coding style, described in
> -Documentation/process/coding-style.rst.  For much of that time, the policies 
> described
> -in that file were taken as being, at most, advisory.  As a result, there is
> -a substantial amount of code in the kernel which does not meet the coding
> -style guidelines.  The presence of that code leads to two independent
> +Documentation/process/coding-style.rst.  For much of that time, the policies
> +described in that file were taken as being, at most, advisory.  As a result,
> +there is a substantial amount of code in the kernel which does not meet the
> +coding style guidelines.  The presence of that code leads to two independent
>  hazards for kernel developers.
>  
>  The first of these is to believe that the kernel coding standards do not
> @@ -343,9 +343,9 @@ user-space developers to know what they are working with. 
>  See
>  Documentation/ABI/README for a description of how this documentation should
>  be formatted and what information needs to be provided.
>  
> -The file Documentation/admin-guide/kernel-parameters.rst describes all of 
> the kernel's
> -boot-time parameters.  Any patch which adds new parameters should add the
> -appropriate entries to this file.
> +The file Documentation/admin-guide/kernel-parameters.rst describes all of
> +the kernel's boot-time parameters.  Any patch which adds new parameters
> +should add the appropriate entries to this file.
>  
>  Any new configuration options must be accompanied by help text which
>  clearly explains the options and when the user might want to select them.

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] Documentation/sphinx: kerneldoc: add "unused-functions"

[Jani Nikula]

On Mon, 03 Apr 2017, Johannes Berg <johan...@sipsolutions.net> wrote:
> On Fri, 2017-03-31 at 15:54 +0300, Jani Nikula wrote:
>> 
>> I'm sure the parameter name could be improved to capture what you
>> mean better; alas I don't have a suggestion.
>
> Yes, that's a fair point - perhaps "functions-not-linked" or something
> like that.
>
>> > Internally this works by collecting (per-file) those functions
>> > (and enums, structs, doc sections...) that are explicitly used,
>> > and invoking the kernel-doc script with "-nofunction" later.
>> 
>> A quick thought that I don't have the time to check now, but should
>> be checked before merging: Is the order of directive extension
>> execution deterministic if the Sphinx run is parallelized (sphinx-
>> build -j)? Is it deterministic within an rst file? Surely it's not
>> deterministic when called from several rst files? The latter is,
>> perhaps, acceptable, but the former not.
>
> Interesting, TBH I never even considered this. How would I even run it
> that way? Presumably "make htmldocs" doesn't do this?

Try 'make SPHINXOPTS=-j8 htmldocs'.

>
> Sphinx documentation (http://www.sphinx-doc.org/en/stable/extdev/) says
> this:
>
> The setup() function can return a dictionary. This is treated by
> Sphinx as metadata of the extension. Metadata keys currently
> recognized are:
> [...]
> 'parallel_read_safe': a boolean that specifies if parallel reading
> of source files can be used when the extension is loaded. It
> defaults to False, i.e. you have to explicitly specify your
> extension to be parallel-read-safe after checking that it is.
>
> We do set this right now, so I guess it'd only be guaranteed to work
> right within a single rst file, and then I should perhaps consider not
> making this state global but somehow linking it to the rst file being
> processed?

Perhaps, but does that defeat the purpose then?

BR,
Jani.

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

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] Documentation/sphinx: kerneldoc: add "unused-functions"

[Jani Nikula]

On Fri, 31 Mar 2017, Johannes Berg <johan...@sipsolutions.net> wrote:
> From: Johannes Berg <johannes.b...@intel.com>
>
> When adding functions one by one into documentation, in order to
> order/group things properly, it's easy to miss things. Allow use
> of the kernel-doc directive with "unused-functions" like this
>
> .. kernel-doc:: 
>:unused-functions:

I'm sure the parameter name could be improved to capture what you mean
better; alas I don't have a suggestion.

>
> to output anything previously unused from that file. This allows
> grouping things but still making sure that the documentation has
> all the functions.
>
> Internally this works by collecting (per-file) those functions
> (and enums, structs, doc sections...) that are explicitly used,
> and invoking the kernel-doc script with "-nofunction" later.

A quick thought that I don't have the time to check now, but should be
checked before merging: Is the order of directive extension execution
deterministic if the Sphinx run is parallelized (sphinx-build -j)? Is it
deterministic within an rst file? Surely it's not deterministic when
called from several rst files? The latter is, perhaps, acceptable, but
the former not.

BR,
Jani.


>
> Signed-off-by: Johannes Berg <johannes.b...@intel.com>
> ---
>  Documentation/sphinx/kerneldoc.py | 16 +++-
>  1 file changed, 15 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/sphinx/kerneldoc.py 
> b/Documentation/sphinx/kerneldoc.py
> index d15e07f36881..79fc1491348a 100644
> --- a/Documentation/sphinx/kerneldoc.py
> +++ b/Documentation/sphinx/kerneldoc.py
> @@ -41,6 +41,9 @@ from sphinx.ext.autodoc import AutodocReporter
>  
>  __version__  = '1.0'
>  
> +# per-file list
> +_used_fns = {}
> +
>  class KernelDocDirective(Directive):
>  """Extract kernel-doc comments from the specified file"""
>  required_argument = 1
> @@ -50,6 +53,7 @@ class KernelDocDirective(Directive):
>  'functions': directives.unchanged_required,
>  'export': directives.unchanged,
>  'internal': directives.unchanged,
> +'unused-functions': directives.unchanged,
>  }
>  has_content = False
>  
> @@ -60,6 +64,10 @@ class KernelDocDirective(Directive):
>  filename = env.config.kerneldoc_srctree + '/' + self.arguments[0]
>  export_file_patterns = []
>  
> +if not filename in _used_fns:
> +_used_fns[filename] = []
> +_used_fns_this_file = _used_fns[filename]
> +
>  # Tell sphinx of the dependency
>  env.note_dependency(os.path.abspath(filename))
>  
> @@ -73,10 +81,16 @@ class KernelDocDirective(Directive):
>  cmd += ['-internal']
>  export_file_patterns = str(self.options.get('internal')).split()
>  elif 'doc' in self.options:
> -cmd += ['-function', str(self.options.get('doc'))]
> +f = str(self.options.get('doc'))
> +cmd += ['-function', f]
> +_used_fns_this_file.append(f)
> +elif 'unused-functions' in self.options:
> +for f in _used_fns_this_file:
> +cmd += ['-nofunction', f]
>  elif 'functions' in self.options:
>  for f in str(self.options.get('functions')).split():
>  cmd += ['-function', f]
> +_used_fns_this_file.append(f)
>  
>  for pattern in export_file_patterns:
>  for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern):

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 01/22] tmplcvt: make the tool more robust

[Jani Nikula]

On Thu, 30 Mar 2017, Mauro Carvalho Chehab <mche...@s-opensource.com> wrote:
> Currently, the script just assumes to be called at
> Documentation/sphinx/. Change it to work on any directory,
> and make it abort if something gets wrong.
>
> Also, be sure that both parameters are specified.
>
> That should avoid troubles like this:
>
> $ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl
> sed: couldn't open file convert_template.sed: No such file or directory
>
> Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
> ---
>  Documentation/sphinx/tmplcvt | 13 +++--
>  1 file changed, 11 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/sphinx/tmplcvt b/Documentation/sphinx/tmplcvt
> index 909a73065e0a..31df8eb7feca 100755
> --- a/Documentation/sphinx/tmplcvt
> +++ b/Documentation/sphinx/tmplcvt
> @@ -7,13 +7,22 @@
>  # fix \_
>  # title line?
>  #
> +set -eu
> +
> +if [ "$2" == "" ]; then

if [ "$#" != "2" ]; then

otherwise with set -u you'll get unbound variable error if you don't
provide $2.

BR,
Jani.

> + echo "$0  "
> + exit
> +fi
> +
> +DIR=$(dirname $0)
>  
>  in=$1
>  rst=$2
>  tmp=$rst.tmp
>  
>  cp $in $tmp
> -sed --in-place -f convert_template.sed $tmp
> +sed --in-place -f $DIR/convert_template.sed $tmp
>  pandoc -s -S -f docbook -t rst -o $rst $tmp
> -sed --in-place -f post_convert.sed $rst
> +sed --in-place -f $DIR/post_convert.sed $rst
>  rm $tmp
> +echo "book writen to $rst"

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 02/22] docs-rst: convert usb docbooks to ReST

[Jani Nikula]

On Thu, 30 Mar 2017, Markus Heiser <markus.hei...@darmarit.de> wrote:
> Hi Mauro,
>
> Am 29.03.2017 um 20:54 schrieb Mauro Carvalho Chehab 
> <mche...@s-opensource.com>:
>
>> As we're moving out of DocBook, let's convert the remaining
>> USB docbooks to ReST.
>> 
>> The transformation itself on this patch is a no-brainer
>> conversion using pandoc.
>
> right, its a no-brainer ;-) I'am not very happy with this
> conversions, some examples see below.
>
> I recommend to use a more elaborate conversion as starting point,
> e.g. from my sphkerneldoc project:
>
> * 
> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/gadget
> * 
> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_musb_glue_layer
> * 
> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_usb_driver
>
> Since these DocBooks hasn't been changed in the last month, the linked reST
> should be up to date.

Markus, I know you've done a lot of work on your conversions, and you
like to advocate them, but AFAICT you have never posted the conversions
as patches to the list. Your project isn't a clone of the kernel
tree. It's a pile of .rst files that nobody knows how to produce from
current upstream DocBook .tmpl files. I'm sorry, but this just doesn't
work that way.

At this point I'd just go with what Mauro has. It's here now, as
patches. We've seen from the GPU documentation that polishing the
one-time initial conversion is, after a point, wasted effort. Having the
documentation in rst attracts more attention and contributions, and any
remaining issues will get ironed out in rst.

This is also one reason I'm in favor of just bulk converting the rest of
the .tmpl files using Documentation/sphinx/tmplcvt, get rid of DocBook
and be done with it, and have the crowds focus on rst.


BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 04/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag

[Jani Nikula]

On Thu, 30 Mar 2017, Jani Nikula <jani.nik...@linux.intel.com> wrote:
> On Wed, 29 Mar 2017, Mauro Carvalho Chehab <mche...@s-opensource.com> wrote:
>> The pandoc conversion is not perfect. Do handwork in order to:
>>
>> - add a title to this chapter;
>> - use the proper warning and note markups;
>> - use kernel-doc to include Kernel header and c files;
>
> Please look at Documentation/sphinx/tmplcvt which takes care of all of
> that.

That said, since you've already manually done the work, you might want
to do another conversion using the script, and diff the results to see
if there's something you've perhaps missed. I'm pretty sure nobody's
going to read patch 2 line-by-line...

BR,
Jani.

>
> BR,
> Jani.
>
>> - remove legacy notes with regards to DocBook;
>> - some other minor adjustments to make it better to read in
>>   text mode and in html.
>>
>> Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
>> ---
>>  Documentation/driver-api/usb/gadget.rst | 69 
>> +
>>  1 file changed, 45 insertions(+), 24 deletions(-)
>>
>> diff --git a/Documentation/driver-api/usb/gadget.rst 
>> b/Documentation/driver-api/usb/gadget.rst
>> index 4fd9862f3f21..c4c76ebb51d3 100644
>> --- a/Documentation/driver-api/usb/gadget.rst
>> +++ b/Documentation/driver-api/usb/gadget.rst
>> @@ -1,3 +1,7 @@
>> +Linux-USB "Gadget" kernel mode API
>> +~~
>> +
>> +
>>  Introduction
>>  
>>  
>> @@ -175,16 +179,12 @@ the gadget, and submitting one or more *struct 
>> usb\_request* buffers to
>>  transfer data. Understand those four data types, and their operations,
>>  and you will understand how this API works.
>>  
>> -**Note**
>> +.. Note::
>>  
>> -This documentation was prepared using the standard Linux kernel
>> -``docproc`` tool, which turns text and in-code comments into SGML
>> -DocBook and then into usable formats such as HTML or PDF. Other than
>> -the "Chapter 9" data types, most of the significant data types and
>> -functions are described here.
>> +Other than the "Chapter 9" data types, most of the significant data
>> +types and functions are described here.
>>  
>> -However, docproc does not understand all the C constructs that are
>> -used, so some relevant information is likely omitted from what you
>> +However, some relevant information is likely omitted from what you
>>  are reading. One example of such information is endpoint
>>  autoconfiguration. You'll have to read the header file, and use
>>  example source code (such as that for "Gadget Zero"), to fully
>> @@ -192,10 +192,10 @@ and you will understand how this API works.
>>  
>>  The part of the API implementing some basic driver capabilities is
>>  specific to the version of the Linux kernel that's in use. The 2.6
>> -kernel includes a *driver model* framework that has no analogue on
>> -earlier kernels; so those parts of the gadget API are not fully
>> -portable. (They are implemented on 2.4 kernels, but in a different
>> -way.) The driver model state is another part of this API that is
>> +and upper kernel versions include a *driver model* framework that has
>> +no analogue on earlier kernels; so those parts of the gadget API are
>> +not fully portable. (They are implemented on 2.4 kernels, but in a
>> +different way.) The driver model state is another part of this API that 
>> is
>>  ignored by the kerneldoc tools.
>>  
>>  The core API does not expose every possible hardware feature, only the
>> @@ -301,18 +301,19 @@ USB 2.0 Chapter 9 Types and Constants
>>  -
>>  
>>  Gadget drivers rely on common USB structures and constants defined in
>> -the  header file, which is standard in Linux 2.6
>> -kernels. These are the same types and constants used by host side
>> +the :ref:`linux/usb/ch9.h ` header file, which is standard in
>> +Linux 2.6+ kernels. These are the same types and constants used by host side
>>  drivers (and usbcore).
>>  
>> -!Iinclude/linux/usb/ch9.h
>>  Core Objects and Methods
>>  
>>  
>>  These are declared in , and are used by gadget
>>  drivers to interact with USB peripheral controller drivers.
>>  
>> -!Iinclude/linux/usb/gadget.h
>> +.. kernel-doc:: include/linux/usb/gadget.h
>> +   :internal

Re: [PATCH 04/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag

[Jani Nikula]

ass storage device". Management functions may also exist,
>  such as "Device Firmware Upgrade".
>  
> -!Iinclude/linux/usb/composite.h !Edrivers/usb/gadget/composite.c
> +.. kernel-doc:: include/linux/usb/composite.h
> +   :internal:
> +
> +.. kernel-doc:: drivers/usb/gadget/composite.c
> +   :export:
> +
>  Composite Device Functions
>  --
>  
> @@ -345,11 +356,21 @@ At this writing, a few of the current gadget drivers 
> have been converted
>  to this framework. Near-term plans include converting all of them,
>  except for "gadgetfs".
>  
> -!Edrivers/usb/gadget/function/f\_acm.c
> -!Edrivers/usb/gadget/function/f\_ecm.c
> -!Edrivers/usb/gadget/function/f\_subset.c
> -!Edrivers/usb/gadget/function/f\_obex.c
> -!Edrivers/usb/gadget/function/f\_serial.c
> +.. kernel-doc:: drivers/usb/gadget/function/f_acm.c
> +   :export:
> +
> +.. kernel-doc:: drivers/usb/gadget/function/f_ecm.c
> +   :export:
> +
> +.. kernel-doc:: drivers/usb/gadget/function/f_subset.c
> +   :export:
> +
> +.. kernel-doc:: drivers/usb/gadget/function/f_obex.c
> +   :export:
> +
> +.. kernel-doc:: drivers/usb/gadget/function/f_serial.c
> +   :export:
> +
>  Peripheral Controller Drivers
>  =
>  
> @@ -475,7 +496,7 @@ can also benefit non-OTG products.
>  -  Also on the host side, a driver must support the OTG "Targeted
> Peripheral List". That's just a whitelist, used to reject peripherals
> not supported with a given Linux OTG host. *This whitelist is
> -   product-specific; each product must modify ``otg_whitelist.h`` to
> +   product-specific; each product must modify* ``otg_whitelist.h`` *to
> match its interoperability specification.*
>  
> Non-OTG Linux hosts, like PCs and workstations, normally have some

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: kerneldoc

[Jani Nikula]

On Mon, 27 Mar 2017, Julia Lawall <julia.law...@lip6.fr> wrote:
> Kerneldoc seems to be written sometimes kerneldoc and sometimes
> kernel-doc.  Which is preferred?  Having two spellings makes it hard to
> use grep to find out what are the conventions for writing kernel
> documentation.

I think "kernel-doc" is the original name for the source code comment
format and the tool that parses it (scripts/kernel-doc). It's also the
name of the Sphinx directive for including the comments into
reStructuredText.

Part of the confusion undoubtedly comes from commit 58af04dff742
("Documentation/sphinx: rename kernel-doc.py to kerneldoc.py") to
appease Python and its module naming conventions.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 0/2] kconfig/mconf: propagate jumping function in search result view

[Jani Nikula]

Yann?

I'd like to have both of these merged, I think they are worthwhile and
simple additions, and they look good to me.


BR,
Jani.


On Thu, 23 Mar 2017, "Du, Changbin" <changbin...@intel.com> wrote:
> Sencond ping... if this is realy not necessary I give up.
>
> On Mon, Mar 06, 2017 at 06:28:50PM +0800, Du, Changbin wrote:
>> Hello, any new update need for this or new comments? :)
>> 
>> On Wed, Feb 08, 2017 at 11:09:37AM +0800, changbin...@intel.com wrote:
>> > From: Changbin Du <changbin...@intel.com>
>> > 
>> > While I am searching something in menuconfig, I hope if I can jump to 
>> > interested
>> > items directly. I even try to add this feature. When I check the code just 
>> > found 
>> > it has already been there but not documented. So why let more developers 
>> > know it?
>> > 
>> > v2: correct spell (Jim)
>> >
>> > Changbin Du (2):
>> >   kconfig/mconf: add jumping tip in title of search result textbox
>> >   Documentation/kconfig: add search jump feature description
>> > 
>> >  Documentation/kbuild/kconfig.txt | 4 
>> >  scripts/kconfig/mconf.c  | 8 
>> >  2 files changed, 8 insertions(+), 4 deletions(-)
>> > 
>> > -- 
>> > 2.7.4
>> > 
>> 
>> -- 
>> Thanks,
>> Changbin Du

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 216/216] Use sphinx.version_info directly instead of parsing

[Jani Nikula]

(What's with the subject [PATCH 216/216], I luckily only saw one patch.)

On Mon, 20 Mar 2017, Remy Leone <remy.le...@inria.fr> wrote:
> From: Rémy Léone <remy.le...@gmail.com>
>
> Using the development version of sphinx caused the parsing of the
> version to fail.
>
> Signed-off-by: Rémy Léone <remy.le...@gmail.com>
> ---
>  Documentation/conf.py   | 2 +-
>  Documentation/sphinx/cdomain.py | 2 +-
>  2 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 7fadb3b..9e9dfa1 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -17,7 +17,7 @@ import os
>  import sphinx
>  
>  # Get Sphinx version
> -major, minor, patch = map(int, sphinx.__version__.split("."))
> +major, minor, patch, _, _ = sphinx.version_info

sphinx.version_info was introduced in Sphinx 1.2, so this change should
be accompanied with

diff --git a/Documentation/conf.py b/Documentation/conf.py
index f2b916158377..00ae12861a96 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -29,7 +29,7 @@ from load_config import loadConfig
 # -- General configuration 
 
 # If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
+needs_sphinx = '1.2'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

---

I suppose we can require 1.2 or later.


BR,
Jani.

>  
>  
>  # If extensions (or modules to document with autodoc) are in another 
> directory,
> diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py
> index df0419c..984e327 100644
> --- a/Documentation/sphinx/cdomain.py
> +++ b/Documentation/sphinx/cdomain.py
> @@ -44,7 +44,7 @@ from sphinx.domains.c import CDomain as Base_CDomain
>  __version__  = '1.0'
>  
>  # Get Sphinx version
> -major, minor, patch = map(int, sphinx.__version__.split("."))
> +major, minor, patch, _, _ = sphinx.version_info
>  
>  def setup(app):

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [Outreachy kernel] [PATCH] Documentation: x86: Fix typos

[Jani Nikula]

On Tue, 14 Mar 2017, Julia Lawall <julia.law...@lip6.fr> wrote:
> On Tue, 14 Mar 2017, Tamara Diaconita wrote:
>
>> Fix typos in x86 directory.
>> Make documentation clear and grammatically correct.
>>
>> Signed-off-by: Tamara Diaconita <diaconita.tam...@gmail.com>
>> ---
>>  Documentation/x86/boot.txt | 4 ++--
>>  1 file changed, 2 insertions(+), 2 deletions(-)
>>
>> diff --git a/Documentation/x86/boot.txt b/Documentation/x86/boot.txt
>> index 5e9b826..694979a 100644
>> --- a/Documentation/x86/boot.txt
>> +++ b/Documentation/x86/boot.txt
>> @@ -336,7 +336,7 @@ Type:read
>>  Offset/size:0x20e/2
>>  Protocol:   2.00+
>>
>> -  If set to a nonzero value, contains a pointer to a NUL-terminated
>> +  If set to a nonzero value, contains a pointer to a NULL-terminated
>>human-readable kernel version number string, less 0x200.  This can
>>be used to display the kernel version to the user.  This value
>>should be less than (0x200*setup_sects).
>> @@ -1105,7 +1105,7 @@ address of the struct boot_params.
>>
>>   EFI HANDOVER PROTOCOL
>>
>> -This protocol allows boot loaders to defer initialisation to the EFI
>> +This protocol allows boot loaders to defer initialization to the EFI
>
> This is an American vs British English issue.  I don't know if the Linux
> kernel prefers one or the other.

We prefer they are best left as they are!

http://marc.info/?i=20170313082328.06d0c...@lwn.net

BR,
Jani.


>
> julia
>
>>  boot stub. The boot loader is required to load the kernel/initrd(s)
>>  from the boot media and jump to the EFI handover protocol entry point
>>  which is hdr->handover_offset bytes from the beginning of
>> --
>> 2.9.3
>>
>> --
>> You received this message because you are subscribed to the Google Groups 
>> "outreachy-kernel" group.
>> To unsubscribe from this group and stop receiving emails from it, send an 
>> email to outreachy-kernel+unsubscr...@googlegroups.com.
>> To post to this group, send email to outreachy-ker...@googlegroups.com.
>> To view this discussion on the web visit 
>> https://groups.google.com/d/msgid/outreachy-kernel/20170314083902.4491-1-diaconita.tamara%40gmail.com.
>> For more options, visit https://groups.google.com/d/optout.
>>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-doc" in
> the body of a message to majord...@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Error in make linkcheckdocs

[Jani Nikula]

On Mon, 13 Mar 2017, Remy Leone <remy.le...@gmail.com> wrote:
> Hello,
>
> I've noticed that this bug started to happen :

Please always try to identify the commit where you see this fails, and
the commit where this worked. And from there on, 'git bisect' is your
friend.

> When I try to launch make linkcheckdocs, the build block and cannot 
> either fail or return. When launching the command :
>
> sphinx-build . output -b linkcheck -vvv
>
> from the Documentation directory, I get the following error:

Sadly, the media documentation have make based prerequisites to running
Sphinx, and you have to run the documentation targets using 'make' from
the kernel source root, e.g. 'make linkcheckdocs', to have them built.

The media rules generate stuff in the output directory, but Sphinx
itself makes it hard to include stuff from the output directory back
into the documentation. So there's a special "kernel-include" directive
that parses environment variables in the argument, and $BUILDDIR gets
used. You'll have to have BUILDDIR environment variable set. You can see
from your error messages that the variable was not expanded.

So please use make to run Sphinx, and have the prerequisites
generated. After that, you can achieve what you want by running

BUILDDIR=output sphinx-build . output -b linkcheck

in the Documentation directory, but it won't update the prerequisites.


BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] docs: Fix htmldocs build failure

[Jani Nikula]

On Sat, 04 Mar 2017, Jonathan Corbet <cor...@lwn.net> wrote:
> On Fri,  3 Mar 2017 22:43:30 +
> Martyn Welch <martyn.we...@collabora.co.uk> wrote:
>
>> Build of HTML docs failing due to conversion of deviceiobook.tmpl in
>> 8a8a602f and regulator.tmpl in 028f2533 to RST without removing from
>> DOCBOOKS in Makefile, resulting (in the case of deviceiobook) the
>> following error:
>> 
>> make[1]: *** No rule to make target 
>> 'Documentation/DocBook/deviceiobook.xml', needed by 
>> 'Documentation/DocBook/deviceiobook.aux.xml'.  Stop.
>> Makefile:1452: recipe for target 'htmldocs' failed
>> make: *** [htmldocs] Error 2
>> 
>> Update DOCBOOKS to reflect available books.
>
> Sigh, that's bad.  Not sure how I achieved that.  Applied, thanks.

Looking at the git logs for the remaining .tmpl files, and how few
updates there have been over the years, IMHO at some point we should
just announce that we'll do a scripted bulk conversion of them to rst
unless people step up to do a better job. Give them a release cycle or
so to do it. Maybe shove the rst files under Documentation/staging, or
label them as such.

BR,
Jani.



-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: making documentation targets on v4.10 with Fedora 25

[Jani Nikula]

On Mon, 20 Feb 2017, Jim Davis <jim.ep...@gmail.com> wrote:
> For the Sphinx targets, htmldocs, pdfdocs, epubdocs, and cleandocs
> failed.  cleandocs works without the O= argument, and arguably the O=
> thing isn't very useful with any of these targets, but it is supported
> by the top-level Makefile.

Why do you say O= isn't useful with the targets? The goal was that it
would work as expected, and it did work in the past. But, as with
everything, if there's no automated testing, it ceases to exist. :(

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v4] Add a target to check broken external links in the Documentation

[Jani Nikula]

On Wed, 15 Feb 2017, Remy Leone <remy.le...@inria.fr> wrote:
> From: Rémy Léone <remy.le...@gmail.com>
>
> Documentation shouldn't have broken links.
> sphinx linkcheck builder scans all documents for external links, tries
> to open them with urllib2, and writes an overview which ones are broken
> and redirected to standard output and to output.txt in the output
> directory.
>
> Signed-off-by: Rémy Léone <remy.le...@gmail.com>

Thanks for the updates!

Reviewed-by: Jani Nikula <jani.nik...@intel.com>
Tested-by: Jani Nikula <jani.nik...@intel.com>

> ---
>  Documentation/DocBook/Makefile | 1 +
>  Documentation/Makefile.sphinx  | 4 
>  Documentation/media/Makefile   | 1 +
>  Makefile   | 2 +-
>  4 files changed, 7 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
> index a6eb7dc..035a6dd 100644
> --- a/Documentation/DocBook/Makefile
> +++ b/Documentation/DocBook/Makefile
> @@ -71,6 +71,7 @@ installmandocs: mandocs
>  # no-op for the DocBook toolchain
>  epubdocs:
>  latexdocs:
> +linkcheckdocs:
>  
>  ###
>  #External programs used
> diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
> index 707c653..c320458 100644
> --- a/Documentation/Makefile.sphinx
> +++ b/Documentation/Makefile.sphinx
> @@ -68,6 +68,9 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath 
> $(BUILDDIR)/$3/$4)
>  htmldocs:
>   @$(foreach var,$(SPHINXDIRS),$(call 
> loop_cmd,sphinx,html,$(var),,$(var)))
>  
> +linkcheckdocs:
> + @$(foreach var,$(SPHINXDIRS),$(call 
> loop_cmd,sphinx,linkcheck,$(var),,$(var)))
> +
>  latexdocs:
>   @$(foreach var,$(SPHINXDIRS),$(call 
> loop_cmd,sphinx,latex,$(var),latex,$(var)))
>  
> @@ -109,6 +112,7 @@ dochelp:
>   @echo  '  pdfdocs - PDF'
>   @echo  '  epubdocs- EPUB'
>   @echo  '  xmldocs - XML'
> + @echo  '  linkcheckdocs   - check for broken external links (will 
> connect to external hosts)'
>   @echo  '  cleandocs   - clean all generated files'
>   @echo
>   @echo  '  make SPHINXDIRS="s1 s2" [target] Generate only docs of folder 
> s1, s2'
> diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
> index 3266360..8df0cf0 100644
> --- a/Documentation/media/Makefile
> +++ b/Documentation/media/Makefile
> @@ -103,6 +103,7 @@ html: all
>  epub: all
>  xml: all
>  latex: $(IMGPDF) all
> +linkcheck:
>  
>  clean:
>   -rm -f $(DOTTGT) $(IMGTGT) ${TARGETS} 2>/dev/null
> diff --git a/Makefile b/Makefile
> index 96e2352..416849c0 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -1444,7 +1444,7 @@ $(help-board-dirs): help-%:
>  
>  # Documentation targets
>  # ---
> -DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs 
> installmandocs epubdocs cleandocs
> +DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs 
> installmandocs epubdocs cleandocs linkcheckdocs
>  PHONY += $(DOC_TARGETS)
>  $(DOC_TARGETS): scripts_basic FORCE
>   $(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3] Add a target to check broken external links in the Documentation

[Jani Nikula]

On Wed, 15 Feb 2017, Remy Leone <remy.le...@inria.fr> wrote:
> From: Rémy Léone <remy.le...@gmail.com>
>
> Documentation shouldn't have broken links.
> sphinx linkcheck builder scans all documents for external links, tries
> to open them with urllib2, and writes an overview which ones are broken
> and redirected to standard output and to output.txt in the output
> directory.
>
> Signed-off-by: Rémy Léone <remy.le...@gmail.com>
> ---
>  Documentation/DocBook/Makefile | 1 +
>  Documentation/Makefile.sphinx  | 4 
>  Documentation/media/Makefile   | 1 +
>  Makefile   | 2 +-
>  4 files changed, 7 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
> index a6eb7dc..ef24346 100644
> --- a/Documentation/DocBook/Makefile
> +++ b/Documentation/DocBook/Makefile
> @@ -71,6 +71,7 @@ installmandocs: mandocs
>  # no-op for the DocBook toolchain
>  epubdocs:
>  latexdocs:
> +linkcheck:

Nope, *just* the Documentation/media/Makefile needed the change from
linkcheckdocs to linkcheck...

make SPHINXDIRS= linkcheckdocs
make[1]: 'linkcheckdocs' is up to date.
make[1]: *** No rule to make target 'linkcheckdocs'.  Stop.
Makefile:1450: recipe for target 'linkcheckdocs' failed
make: *** [linkcheckdocs] Error 2

BR,
Jani.


>  
>  ###
>  #External programs used
> diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
> index 707c653..c320458 100644
> --- a/Documentation/Makefile.sphinx
> +++ b/Documentation/Makefile.sphinx
> @@ -68,6 +68,9 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath 
> $(BUILDDIR)/$3/$4)
>  htmldocs:
>   @$(foreach var,$(SPHINXDIRS),$(call 
> loop_cmd,sphinx,html,$(var),,$(var)))
>  
> +linkcheckdocs:
> + @$(foreach var,$(SPHINXDIRS),$(call 
> loop_cmd,sphinx,linkcheck,$(var),,$(var)))
> +
>  latexdocs:
>   @$(foreach var,$(SPHINXDIRS),$(call 
> loop_cmd,sphinx,latex,$(var),latex,$(var)))
>  
> @@ -109,6 +112,7 @@ dochelp:
>   @echo  '  pdfdocs - PDF'
>   @echo  '  epubdocs- EPUB'
>   @echo  '  xmldocs - XML'
> + @echo  '  linkcheckdocs   - check for broken external links (will 
> connect to external hosts)'
>   @echo  '  cleandocs   - clean all generated files'
>   @echo
>   @echo  '  make SPHINXDIRS="s1 s2" [target] Generate only docs of folder 
> s1, s2'
> diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
> index 3266360..8df0cf0 100644
> --- a/Documentation/media/Makefile
> +++ b/Documentation/media/Makefile
> @@ -103,6 +103,7 @@ html: all
>  epub: all
>  xml: all
>  latex: $(IMGPDF) all
> +linkcheck:
>  
>  clean:
>   -rm -f $(DOTTGT) $(IMGTGT) ${TARGETS} 2>/dev/null
> diff --git a/Makefile b/Makefile
> index 96e2352..416849c0 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -1444,7 +1444,7 @@ $(help-board-dirs): help-%:
>  
>  # Documentation targets
>  # ---
> -DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs 
> installmandocs epubdocs cleandocs
> +DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs 
> installmandocs epubdocs cleandocs linkcheckdocs
>  PHONY += $(DOC_TARGETS)
>  $(DOC_TARGETS): scripts_basic FORCE
>   $(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] Add a target to check broken external links in the Documentation

[Jani Nikula]

On Tue, 14 Feb 2017, Remy Leone <remy.le...@inria.fr> wrote:
> From: Rémy Léone <remy.le...@gmail.com>
>
> Documentation shouldn't have broken links.
> sphinx linkcheck builder scans all documents for external links, tries
> to open them with urllib2, and writes an overview which ones are broken
> and redirected to standard output and to output.txt in the output
> directory.
>
> Signed-off-by: Rémy Léone <remy.le...@gmail.com>
> ---
> Changes in v2:
>
> - Add a more descriptive commit message
> - Add message to make help output about connection to external host
> - Add no-op for:
> - Documentation/DocBook/Makefile
> - Documentation/media/Makefile
> - Remove sphinx.builders.linkcheck include
> - Change from linkcheck to linkcheckdocs
>
>  Documentation/DocBook/Makefile | 1 +
>  Documentation/Makefile.sphinx  | 4 
>  Documentation/media/Makefile   | 1 +
>  Makefile   | 2 +-
>  4 files changed, 7 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
> index a6eb7dc..035a6dd 100644
> --- a/Documentation/DocBook/Makefile
> +++ b/Documentation/DocBook/Makefile
> @@ -71,6 +71,7 @@ installmandocs: mandocs
>  # no-op for the DocBook toolchain
>  epubdocs:
>  latexdocs:
> +linkcheckdocs:
>  
>  ###
>  #External programs used
> diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
> index 707c653..c320458 100644
> --- a/Documentation/Makefile.sphinx
> +++ b/Documentation/Makefile.sphinx
> @@ -68,6 +68,9 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath 
> $(BUILDDIR)/$3/$4)
>  htmldocs:
>   @$(foreach var,$(SPHINXDIRS),$(call 
> loop_cmd,sphinx,html,$(var),,$(var)))
>  
> +linkcheckdocs:
> + @$(foreach var,$(SPHINXDIRS),$(call 
> loop_cmd,sphinx,linkcheck,$(var),,$(var)))
> +
>  latexdocs:
>   @$(foreach var,$(SPHINXDIRS),$(call 
> loop_cmd,sphinx,latex,$(var),latex,$(var)))
>  
> @@ -109,6 +112,7 @@ dochelp:
>   @echo  '  pdfdocs - PDF'
>   @echo  '  epubdocs- EPUB'
>   @echo  '  xmldocs - XML'
> + @echo  '  linkcheckdocs   - check for broken external links (will 
> connect to external hosts)'
>   @echo  '  cleandocs   - clean all generated files'
>   @echo
>   @echo  '  make SPHINXDIRS="s1 s2" [target] Generate only docs of folder 
> s1, s2'
> diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
> index 3266360..d576ef1 100644
> --- a/Documentation/media/Makefile
> +++ b/Documentation/media/Makefile
> @@ -103,6 +103,7 @@ html: all
>  epub: all
>  xml: all
>  latex: $(IMGPDF) all
> +linkcheckdocs:

Argh, this makefile is called with the Sphinx builder as target,
i.e. linkcheck instead of linkcheckdocs, leading to

make[2]: *** No rule to make target 'linkcheck'.  Stop.

We do expect contributors to try to weed out things like this
themselves.

Please apply the below change on top, and this is

Reviewed-by: Jani Nikula <jani.nik...@intel.com>
Tested-by: Jani Nikula <jani.nik...@intel.com>


BR,
Jani.


diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
index d576ef112b26..8df0cf01bcb2 100644
--- a/Documentation/media/Makefile
+++ b/Documentation/media/Makefile
@@ -103,7 +103,7 @@ html: all
 epub: all
 xml: all
 latex: $(IMGPDF) all
-linkcheckdocs:
+linkcheck:
 
 clean:
-rm -f $(DOTTGT) $(IMGTGT) ${TARGETS} 2>/dev/null



>  
>  clean:
>   -rm -f $(DOTTGT) $(IMGTGT) ${TARGETS} 2>/dev/null
> diff --git a/Makefile b/Makefile
> index 96e2352..416849c0 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -1444,7 +1444,7 @@ $(help-board-dirs): help-%:
>  
>  # Documentation targets
>  # ---
> -DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs 
> installmandocs epubdocs cleandocs
> +DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs 
> installmandocs epubdocs cleandocs linkcheckdocs
>  PHONY += $(DOC_TARGETS)
>  $(DOC_TARGETS): scripts_basic FORCE
>   $(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Add a target to check broken external links in the Documentation

[Jani Nikula]

On Tue, 14 Feb 2017, Jonathan Corbet <cor...@lwn.net> wrote:
> On Tue, 14 Feb 2017 15:52:10 +0200
> Jani Nikula <jani.nik...@linux.intel.com> wrote:
>
>> On Tue, 14 Feb 2017, Remy Leone <remy.le...@gmail.com> wrote:
>> > I've got a question, when I receive review on a patch, is it better to 
>> > resubmit or to reply inside the same thread?  
>> 
>> Depends on the subsystem, maintainer, and the phase of the Moon. ;)
>> 
>> I'm not the documentation maintainer, but personally I prefer sending
>> updated patches in-reply-to the previous ones when they are single
>> patches or updates to just a few patches in a series. When updating more
>> than a few patches in a series, I'd repost the entire series as a new
>> thread and reference the previous series in a cover letter.
>
> I don't have strong opinions on this matter, but my general preference is
> to get revised patches in a new thread; they stand out a bit more in my
> disastrous inbox that way...

This reminds me, Remy, it's generally preferred to Cc any people who
have commented on your patch when sending updated versions.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Add a target to check broken external links in the Documentation

[Jani Nikula]

On Tue, 14 Feb 2017, Remy Leone <remy.le...@gmail.com> wrote:
> I've got a question, when I receive review on a patch, is it better to 
> resubmit or to reply inside the same thread?

Depends on the subsystem, maintainer, and the phase of the Moon. ;)

I'm not the documentation maintainer, but personally I prefer sending
updated patches in-reply-to the previous ones when they are single
patches or updates to just a few patches in a series. When updating more
than a few patches in a series, I'd repost the entire series as a new
thread and reference the previous series in a cover letter.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Add a target to check broken external links in the Documentation

[Jani Nikula]

Hi Remy, I like what this does, and it'll be helpful in ensuring we
don't have broken links. However, there are some issues.

On Tue, 14 Feb 2017, Remy Leone <remy.le...@inria.fr> wrote:
> From: Rémy Léone <remy.le...@gmail.com>

This area here is for the commit message, describing what linkcheck
does, why you think it's a good idea, and that anyone running it should
be aware that it'll try to connect to all URLs referenced in the
documentation.

This also needs a line in 'make help' output, with the warning that
it'll connect.

> Signed-off-by: Rémy Léone <remy.le...@gmail.com>
> ---
>  Documentation/Makefile.sphinx | 3 +++
>  Documentation/conf.py | 2 +-
>  Makefile  | 2 +-
>  3 files changed, 5 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
> index 707c653..bfacb1b 100644
> --- a/Documentation/Makefile.sphinx
> +++ b/Documentation/Makefile.sphinx
> @@ -68,6 +68,9 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath 
> $(BUILDDIR)/$3/$4)
>  htmldocs:
>   @$(foreach var,$(SPHINXDIRS),$(call 
> loop_cmd,sphinx,html,$(var),,$(var)))
>  
> +linkcheck:
> + @$(foreach var,$(SPHINXDIRS),$(call 
> loop_cmd,sphinx,linkcheck,$(var),,$(var)))

Documentation/DocBook/Makefile needs a no-op target for
linkcheck. Unfortunately, so does Documentation/media/Makefile. (Did you
not see the "make[2]: *** No rule to make target 'linkcheck'.  Stop."
warnings?)

> +
>  latexdocs:
>   @$(foreach var,$(SPHINXDIRS),$(call 
> loop_cmd,sphinx,latex,$(var),latex,$(var)))
>  
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 1ac958c..324fa92 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -34,7 +34,7 @@ from load_config import loadConfig
>  # Add any Sphinx extension module names here, as strings. They can be
>  # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
>  # ones.
> -extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain']
> +extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 
> 'sphinx.builders.linkcheck']

This results in "WARNING: extension 'sphinx.builders.linkcheck' has no
setup() function; is it really a Sphinx extension module?"

I don't think you need to add builders to extensions at all, do you?
Seems to work just fine without.

>  
>  # The name of the math extension changed on Sphinx 1.4
>  if major == 1 and minor > 3:
> diff --git a/Makefile b/Makefile
> index 96e2352..1f93b3c 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -1444,7 +1444,7 @@ $(help-board-dirs): help-%:
>  
>  # Documentation targets
>  # ---
> -DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs 
> installmandocs epubdocs cleandocs
> +DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs 
> installmandocs epubdocs cleandocs linkcheck

Historically the documentation targets were '%docs', i.e. anything with
the docs suffix. I thought it would be better to call out the targets
explicitly, but perhaps that's not the case if it encourages targets
without docs suffix. Otherwise we'll have to keep touching
no-dot-config-targets too, which is not desirable ('make linkcheck'
as-is runs the config target).

In short, I think this should be called linkcheckdocs.


BR,
Jani.

>  PHONY += $(DOC_TARGETS)
>  $(DOC_TARGETS): scripts_basic FORCE
>   $(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: make pdfdoc errors with 4.10-rc7

[Jani Nikula]

On Thu, 09 Feb 2017, Jim Davis <jim.ep...@gmail.com> wrote:
> On a Fedora 25 system, make pdfdocs is failing with
>
> [jim@krebstar linux-rc]$ grep -v -i 'warning:' /tmp/make-pdfdocs.err
> /data/linux-rc/Documentation/doc-guide/sphinx.rst:110: ERROR: Unknown
> target name: "sphinx c domain".

This one is caused by 1dc4bbf0b268 ("docs-rst: doc-guide: split the
kernel-documentation.rst contents"). Both kernel-doc.rst and sphinx.rst
reference Sphinx C Domain, but only kernel-doc.rst copied it over from
the source document. sphinx.rst lacks:

.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html

Not sure if this one is able to eventually cause the pdfdocs failure.

BR,
Jani.


> ./include/net/cfg80211.h:3154: ERROR: Unexpected indentation.
> ./include/net/mac80211.h:3214: ERROR: Unexpected indentation.
> ./include/net/mac80211.h:3219: ERROR: Unexpected indentation.
> ./include/net/mac80211.h:1773: ERROR: Unexpected indentation.
> ./kernel/time/timer.c:1240: ERROR: Unexpected indentation.
> ./kernel/time/timer.c:1242: ERROR: Unexpected indentation.
> ./include/linux/wait.h:124: ERROR: Unexpected indentation.
> ./include/linux/spi/spi.h:369: ERROR: Unexpected indentation.
> ./drivers/usb/core/message.c:481: ERROR: Unexpected indentation.
> /data/linux-rc/Documentation/driver-api/usb.rst:623: ERROR: Unknown
> target name: "usb_type".
> /data/linux-rc/Documentation/driver-api/usb.rst:623: ERROR: Unknown
> target name: "usb_dir".
> /data/linux-rc/Documentation/driver-api/usb.rst:623: ERROR: Unknown
> target name: "usb_recip".
> /data/linux-rc/Documentation/driver-api/usb.rst:689: ERROR: Unknown
> target name: "usbdevfs_urb_type".
> ./sound/soc/soc-core.c:2508: ERROR: Unknown target name: "snd_soc_daifmt".
> ./sound/core/jack.c:312: ERROR: Unknown target name: "snd_jack_btn".
> make[2]: *** [linux-user.pdf] Error 1
> make[1]: *** [pdfdocs] Error 2
> make: *** [pdfdocs] Error 2

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 1/2] kconfig/mconf: add jumping tip in title of search result textbox

[Jani Nikula]

On Wed, 08 Feb 2017, changbin...@intel.com wrote:
> From: Changbin Du <changbin...@intel.com>
>
> Prompt user how to quickly jump to the item he/she is interested in.
>
> Signed-off-by: Changbin Du <changbin...@intel.com>
> Reviewed-by: Jani Nikula <jani.nik...@linux.intel.com>

This is assuming too much... but I looked at it now, and it looks good
to me.

Thanks,
Jani.

> ---
>  scripts/kconfig/mconf.c | 8 
>  1 file changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/scripts/kconfig/mconf.c b/scripts/kconfig/mconf.c
> index 315ce2c..23d5681 100644
> --- a/scripts/kconfig/mconf.c
> +++ b/scripts/kconfig/mconf.c
> @@ -443,10 +443,10 @@ static void search_conf(void)
>  
>   res = get_relations_str(sym_arr, );
>   set_subtitle();
> - dres = show_textbox_ext(_("Search Results"), (char *)
> - str_get(), 0, 0, keys, ,
> - , _text, (void *)
> - );
> + dres = show_textbox_ext(
> + _("Search Results (type the number to jump)"),
> + (char *)str_get(), 0, 0, keys, ,
> + , _text, (void *));
>   again = false;
>   for (i = 0; i < JUMP_NB && keys[i]; i++)
>   if (dres == keys[i]) {

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/3] doc-rst: Delete output of failed dot-SVG conversion

[Jani Nikula]

On Sat, 04 Feb 2017, Ben Hutchings <b...@decadent.org.uk> wrote:
> On Wed, 2017-02-01 at 13:20 -0700, Jonathan Corbet wrote:
>> On Tue, 31 Jan 2017 15:37:50 +
>> Ben Hutchings <b...@decadent.org.uk> wrote:
>> 
>> > > I'd just use dot -o.  
>> > 
>> > That does make more sense.  I looked for such an option before
>> > writing
>> > this, but the manual page doesn't mention it!
>> 
>> Can I get an updated patch from you?  Then I'll apply the whole
>> set...
>
> I've now tested this, and found that dot still touches the output file
> even if it fails.  So changing to -o doesn't fix anything.

Ugh. :(

> Please apply the original patch.

Ack.


BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] kconfig/mconf: add jumping tip in title of search result textbox

[Jani Nikula]

On Mon, 06 Feb 2017, changbin...@intel.com wrote:
> From: Changbin Du <changbin...@intel.com>
>
> Prompt user how to quickly jump to the item he/she is interested in.

:o

All these years. I... I didn't know. Thanks!

> Signed-off-by: Changbin Du <changbin...@intel.com>
> ---
>  scripts/kconfig/mconf.c | 8 
>  1 file changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/scripts/kconfig/mconf.c b/scripts/kconfig/mconf.c
> index 315ce2c..23d5681 100644
> --- a/scripts/kconfig/mconf.c
> +++ b/scripts/kconfig/mconf.c
> @@ -443,10 +443,10 @@ static void search_conf(void)
>  
>   res = get_relations_str(sym_arr, );
>   set_subtitle();
> - dres = show_textbox_ext(_("Search Results"), (char *)
> - str_get(), 0, 0, keys, ,
> - , _text, (void *)
> - );
> + dres = show_textbox_ext(
> + _("Search Results (type the number to jump)"),
> + (char *)str_get(), 0, 0, keys, ,
> + , _text, (void *));

It would be even better and discoverable if this could be turned into a
dialog menu, so that you could navigate the search results using arrow
keys and hit enter to choose. But this is already an improvement.

>   again = false;
>       for (i = 0; i < JUMP_NB && keys[i]; i++)
>   if (dres == keys[i]) {

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH RESEND] Documentation/sphinx: prevent generation of .pyc files in the source tree

[Jani Nikula]

On Wed, 01 Feb 2017, Jonathan Corbet <cor...@lwn.net> wrote:
> On Tue, 31 Jan 2017 20:18:05 +0200
> Jani Nikula <jani.nik...@intel.com> wrote:
>
>> Considering the small amount of python code to compile (assuming sphinx
>> itself has .pyc around), the impact on build is neglible.
>
> Hey...don't you know that performance-impacting patches need benchmarks?

Heh, I was briefly worried at this point! :)

>
> Sphinx-only htmldocs build before:
>
>   real2m26.063s
>   user2m19.184s
>   sys 0m5.429s
>
> After:
>
>   real2m26.342s
>   user2m20.445s
>   sys 0m5.611s
>
> You owe me 0.279 seconds :)
>
> (Applied, thanks).
>
> jon

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH RESEND] Documentation/sphinx: prevent generation of .pyc files in the source tree

[Jani Nikula]

Use PYTHONDONTWRITEBYTECODE=1 to prevent python from creating .pyc files
in the source tree. Python 3.2 has a __pycache__ scheme [1], but before
that the only alternative seems to be to copy the source files to the
build tree to ensure the .pyc files are created there too. Just prevent
.pyc file generation for simplicity.

Considering the small amount of python code to compile (assuming sphinx
itself has .pyc around), the impact on build is neglible.

[1] 
http://stackoverflow.com/questions/3522079/changing-the-directory-where-pyc-files-are-created

References: 
http://lkml.kernel.org/r/camuhmdvxqph7-9xj+ye_pgoa+-fe0969cskoehyh3uubycr...@mail.gmail.com
Reported-by: Geert Uytterhoeven <ge...@linux-m68k.org>
References: http://lkml.kernel.org/r/1485816692.2900.17.ca...@decadent.org.uk
Reported-by: Ben Hutchings <b...@decadent.org.uk>
Cc: Jonathan Corbet <cor...@lwn.net>
Signed-off-by: Jani Nikula <jani.nik...@intel.com>
---
 Documentation/Makefile.sphinx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
index 707c65337ebf..91f541a52884 100644
--- a/Documentation/Makefile.sphinx
+++ b/Documentation/Makefile.sphinx
@@ -55,6 +55,7 @@ loop_cmd = $(echo-cmd) $(cmd_$(1))
 
 quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
   cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) 
$(build)=Documentation/media $2;\
+   PYTHONDONTWRITEBYTECODE=1 \
BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath 
$(srctree)/$(src)/$5/$(SPHINX_CONF)) \
$(SPHINXBUILD) \
-b $2 \
-- 
2.1.4

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

Re: [PATCH 2/3] doc-rst: Delete output of failed dot-SVG conversion

[Jani Nikula]

On Tue, 31 Jan 2017, Ben Hutchings <b...@decadent.org.uk> wrote:
> As we use redirection to create the SVG file, even a failed conversion
> will create the file and 'make' will consider it up-to-date if the
> build is retried.  We should delete it in case of failure.
>
> Fixes: ec868e4ee2bc ("docs-rst: media: build SVG from graphviz files")
> Signed-off-by: Ben Hutchings <b...@decadent.org.uk>
> ---
>  Documentation/media/Makefile | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
> index 32663602ff25..730d73db7c7a 100644
> --- a/Documentation/media/Makefile
> +++ b/Documentation/media/Makefile
> @@ -36,7 +36,7 @@ quiet_cmd_genpdf = GENPDF  $2
>cmd_genpdf = convert $2 $3
>  
>  quiet_cmd_gendot = DOT $2
> -  cmd_gendot = dot -Tsvg $2 > $3
> +  cmd_gendot = dot -Tsvg $2 > $3 || { rm -f $3; exit 1; }

I'd just use dot -o.

>  
>  %.pdf: %.svg
>   @$(call cmd,genpdf,$<,$@)
>

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Sphinx builds always write to the source directory

[Jani Nikula]

On Tue, 31 Jan 2017, Ben Hutchings <b...@decadent.org.uk> wrote:
> I'm having trouble with the Debian packaging of kernel documentation. 
> We try to build everything in a separate output directory (underneath
> debian/build), but the new Sphinx-based build system writes to the
> source directory.
>
> Firstly, Python creates bytecode files alongside the module sources. 
> This could be avoided by setting environment variable
> PYTHONDONTWRITEBYTECODE=1, at the expense of requiring recompilation
> more often.

I've sent the patch a few times.

http://lkml.kernel.org/r/1479916579-17151-1-git-send-email-jani.nik...@intel.com

> Secondly, starting with 4.10, Documentation/media/Makefile converts
> from dot to SVG and from SVG to PDF in the source directory.  It seems
> like it should be possible to put the converted files in the output
> directory, but I don't know how to tell Sphinx to find them there.
>
> Are these issues likely to be fixed?
>
> Ben.

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation/sphinx: make targets independent of Sphinx work for HAVE_SPHINX=0

[Jani Nikula]

On Mon, 30 Jan 2017, Jani Nikula <jani.nik...@intel.com> wrote:
> Make targets that don't depend on Sphinx work without warnings about
> missing Sphinx. 'make cleandocs' will work without Sphinx just fine, and
> the targets that are no-ops for Sphinx should just be skipped. Move them
> outside of the HAVE_SPHINX checks to take precedence over the .DEFAULT
> target for HAVE_SPHINX=0.
>
> Reported-by: Jim Davis <jim.ep...@gmail.com>
> Reference: 
> http://lkml.kernel.org/r/ca+r1zhjrvqkjpxgogb_boax2hkfb+qqcttzffbmfeh1mfee...@mail.gmail.com

Cc: sta...@vger.kernel.org

Might not be unreasonable.


> Signed-off-by: Jani Nikula <jani.nik...@intel.com>
> ---
>  Documentation/Makefile.sphinx | 7 +--
>  1 file changed, 5 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
> index 707c65337ebf..d1aa7ffdea64 100644
> --- a/Documentation/Makefile.sphinx
> +++ b/Documentation/Makefile.sphinx
> @@ -90,6 +90,11 @@ epubdocs:
>  xmldocs:
>   @$(foreach var,$(SPHINXDIRS),$(call 
> loop_cmd,sphinx,xml,$(var),xml,$(var)))
>  
> +endif # HAVE_SPHINX
> +
> +# The following targets are independent of HAVE_SPHINX, and the rules should
> +# work or silently pass without Sphinx.
> +
>  # no-ops for the Sphinx toolchain
>  sgmldocs:
>  psdocs:
> @@ -100,8 +105,6 @@ cleandocs:
>   $(Q)rm -rf $(BUILDDIR)
>   $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) -C Documentation/media clean
>  
> -endif # HAVE_SPHINX
> -
>  dochelp:
>       @echo  ' Linux kernel internal documentation in different formats 
> (Sphinx):'
>   @echo  '  htmldocs- HTML'

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html