Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Fri, 19 Apr 2019 07:27:35 -0300
From:   Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
To:     Jani Nikula <jani.nikula@linux.intel.com>
Cc:     Linux Doc Mailing List <linux-doc@vger.kernel.org>,
        Mauro Carvalho Chehab <mchehab@infradead.org>,
        linux-kernel@vger.kernel.org, Jonathan Corbet <corbet@lwn.net>
Subject: Re: [PATCH] docs: hwmon: convert three docs to ReST format
Message-ID: <20190419072735.46f26b87@coco.lan>
In-Reply-To: <877ebqgv79.fsf@intel.com>
References: <287cf72fc213656c1593f8bd42feb62f7a5f26e7.1555580417.git.mchehab+samsung@kernel.org>
        <87k1frgysq.fsf@intel.com>
        <20190418151028.341723f7@coco.lan>
        <877ebqgv79.fsf@intel.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

Em Fri, 19 Apr 2019 13:12:26 +0300
Jani Nikula <jani.nikula@linux.intel.com> escreveu:

> On Thu, 18 Apr 2019, Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> > Em Thu, 18 Apr 2019 17:42:29 +0300
> > Jani Nikula <jani.nikula@linux.intel.com> escreveu:
> >  
> >> On Thu, 18 Apr 2019, Mauro Carvalho Chehab <mchehab+samsung@kernel.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@kernel.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.

Actually, there are a few that has, including the doc-guide

$ git grep \\.rst $(find Documentation/ -name index.rst)|cut -d: -f1|sort|uniq
Documentation/admin-guide/mm/index.rst
Documentation/doc-guide/index.rst
Documentation/filesystems/ext4/index.rst
Documentation/filesystems/index.rst
Documentation/hwmon/index.rst
Documentation/translations/it_IT/doc-guide/index.rst
Documentation/translations/it_IT/kernel-hacking/index.rst
Documentation/translations/it_IT/process/index.rst
Documentation/translations/zh_CN/process/index.rst

(I'm looking at linux-next).

Clearly, the Documentation/doc-guide/index.rst has it:

=================================
How to write kernel documentation
=================================

.. toctree::
   :maxdepth: 1

   sphinx.rst
   kernel-doc.rst
   parse-headers.rst

Anyway I'll send a patch removing the extra .rst from hwmon, to
be applied after this one, and another one for the doc-guide.

> 
> > 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@pengutronix.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.
> 
> 


Thanks,
Mauro