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

[Mauro Carvalho Chehab]

Em Thu, 18 Apr 2019 17:42:29 +0300
Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> escreveu:

> On Thu, 18 Apr 2019, Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx> 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@xxxxxxxxxx>
> > ---
> >  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.

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

Thanks,
Mauro