linux-kernel - Re: [PATCH v2 25/79] docs: convert docs to ReST and rename to *.rst

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: <20190426064609.7f00e013@coco.lan>
Date:   Fri, 26 Apr 2019 06:46:09 -0300
From:   Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
To:     Mark Brown <broonie@...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>,
        Sebastian Reichel <sre@...nel.org>,
        Bjorn Helgaas <bhelgaas@...gle.com>,
        "Rafael J. Wysocki" <rjw@...ysocki.net>,
        Viresh Kumar <viresh.kumar@...aro.org>,
        Len Brown <len.brown@...el.com>, Pavel Machek <pavel@....cz>,
        Nishanth Menon <nm@...com>, Stephen Boyd <sboyd@...nel.org>,
        Liam Girdwood <lgirdwood@...il.com>,
        Mathieu Poirier <mathieu.poirier@...aro.org>,
        Suzuki K Poulose <suzuki.poulose@....com>,
        Harry Wei <harryxiyou@...il.com>,
        Alex Shi <alex.shi@...ux.alibaba.com>,
        Thomas Gleixner <tglx@...utronix.de>,
        Ingo Molnar <mingo@...hat.com>, Borislav Petkov <bp@...en8.de>,
        "H. Peter Anvin" <hpa@...or.com>, x86@...nel.org,
        Jani Nikula <jani.nikula@...ux.intel.com>,
        Joonas Lahtinen <joonas.lahtinen@...ux.intel.com>,
        Rodrigo Vivi <rodrigo.vivi@...el.com>,
        David Airlie <airlied@...ux.ie>,
        Daniel Vetter <daniel@...ll.ch>,
        Johannes Berg <johannes@...solutions.net>,
        "David S. Miller" <davem@...emloft.net>, linux-pm@...r.kernel.org,
        linux-pci@...r.kernel.org, linux-arm-kernel@...ts.infradead.org,
        intel-gfx@...ts.freedesktop.org, dri-devel@...ts.freedesktop.org,
        linux-wireless@...r.kernel.org, netdev@...r.kernel.org
Subject: Re: [PATCH v2 25/79] docs: convert docs to ReST and rename to *.rst

Hi Mark,

Em Thu, 25 Apr 2019 19:07:58 +0100
Mark Brown <broonie@...nel.org> escreveu:

> On Mon, Apr 22, 2019 at 10:27:14AM -0300, Mauro Carvalho Chehab wrote:
> > Convert the PM documents to ReST, in order to allow them to
> > build with Sphinx.  
> 
> This is massively CCed covering a large range of subsystems and is patch
> 25 of a 79 patch series so I've no context for what's going on here or
> why...  

There are two goals of this series:

1) to prepare for placing the new *.rst files under Documentation/ into an
   index file, being part of one of the books. Most of the stuff covered
   on this series either fit at the system admin guide or at the
   Kernel API documentation book;

2) to ensure that, if some edition on a file would cause warnings at
   Sphinx build, someone will notice and submit a followup patch.

You can see more details at patch 00/79:
	https://lore.kernel.org/lkml/20190422115110.26443b44@coco.lan/

In order to do that, this series has one patch per Documentation/*
sub-directory. This specific one is for the documents under
Documentation/power/ [1].

[1] btw, the title of this specific patch should be, instead:
	docs: power: convert docs to ReST and rename to *.rst

The series is long because I'm trying to cover a significant part
of the documentation files. In any case, except if an eventual
conflict might rise on some file, this patch is independent from
all other files, and should be safe to apply directly via the
subsystem git tree.

I'm working on a follow-up patch series that should be adding the
power/index.rst file into another index file - probably at
Documentation/index.rst[1]. As such patch will be adding a lot of other
index files, the best would be to merge it via the docs tree, in
order to avoid conflicts.

[1] such patch will be removing the ":orphan:" meta-tag from it
(that basically tells the build system to not produce warnings if
the file is not directly or indirectly referenced by the main
index file).

Thanks,
Mauro