linux-kernel - Re: [PATCH] docs: hwmon: convert three docs to ReST format

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <877ebqgv79.fsf@intel.com>
Date:   Fri, 19 Apr 2019 13:12:26 +0300
From:   Jani Nikula <jani.nikula@...ux.intel.com>
To:     Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        linux-kernel@...r.kernel.org, Jonathan Corbet <corbet@....net>
Subject: Re: [PATCH] docs: hwmon: convert three docs to ReST format

On Thu, 18 Apr 2019, Mauro Carvalho Chehab <mchehab+samsung@...nel.org> wrote:
> Em Thu, 18 Apr 2019 17:42:29 +0300
> Jani Nikula <jani.nikula@...ux.intel.com> escreveu:
>
>> On Thu, 18 Apr 2019, Mauro Carvalho Chehab <mchehab+samsung@...nel.org> wrote:
>> > Those three new drivers were missed on the initial conversion
>> > to ReST format. So:
>> >
>> > - Rename them to .rst;
>> > - Add them to the hwmon index.rst index;
>> > - add some blank lines at the "Supported systems:" part, in
>> >   order to allow Sphinx to properly identify new lines,
>> >   suppressing warnings and avoid it to output some random
>> >   lines in bold;
>> > - When multiple authors are involved, change the authors
>> >   part to a list, in order to avoid adding blank lines.
>> > - adjust the table cells (one of the tables seemed to be
>> >   assuming that tab is 4 positions instead of 8) and add
>> >   the table markup.
>> > - be sure that the section markups have the same number of
>> >   characters as the section title.
>> >
>> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
>> > ---
>> >  Documentation/hwmon/index.rst                 |  3 +++
>> >  Documentation/hwmon/{ir38064 => ir38064.rst}  | 21 ++++++++++++-------
>> >  .../hwmon/{isl68137 => isl68137.rst}          | 16 ++++++++++----
>> >  .../hwmon/{lochnagar => lochnagar.rst}        |  7 +++++--
>> >  4 files changed, 33 insertions(+), 14 deletions(-)
>> >  rename Documentation/hwmon/{ir38064 => ir38064.rst} (76%)
>> >  rename Documentation/hwmon/{isl68137 => isl68137.rst} (85%)
>> >  rename Documentation/hwmon/{lochnagar => lochnagar.rst} (93%)
>> >
>> > diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst
>> > index 893804414510..3fa14fe7b49c 100644
>> > --- a/Documentation/hwmon/index.rst
>> > +++ b/Documentation/hwmon/index.rst
>> > @@ -65,6 +65,8 @@ Hardware Monitoring Kernel Drivers
>> >     ina2xx.rst
>> >     ina3221.rst
>> >     ir35221.rst
>> > +   ir38064.rst
>> > +   isl68137.rst  
>> 
>> Didn't notice it on the first patch adding index.rst, but I don't think
>> it's customary to add .rst suffix to the toctree.
>
> Provided that all documents are at the same time, I guess it
> doesn't matter having a .rst there or not.

Parse error. No other index.rst has the suffixes.

> Btw, newer versions of Sphinx build can work with other formats
> like markdown. I suspect that, if we end mixing markdown documents,
> it would be worth having the extension there.
>
> FYI, someone recently added a markdown file at the tree:
>
> commit e453fa60e086786fe89ba15ee8fef80bc2e6ecc3
> Author: Sascha Hauer <s.hauer@...gutronix.de>
> Date:   Fri Sep 7 14:36:46 2018 +0200
>
>     Documentation: ubifs: Add authentication whitepaper
>
> 	Documentation/filesystems/ubifs-authentication.md
>
> IMO, the best would be to just run pandoc into it and convert
> to .rst, than to mix different markup languages.

Agreed. I'd rather we keep it all rst.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Graphics Center