Message ID | cover.1555382110.git.mchehab+samsung@kernel.org (mailing list archive) |
---|---|
Headers | show |
Series | Convert files to ReST | expand |
On Mon 2019-04-15 23:55:50, Mauro Carvalho Chehab wrote: > Convert the PM documents to ReST, in order to allow them to > build with Sphinx. > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Pavel Machek <pavel@ucw.cz>
On Tuesday, April 16, 2019 4:55:50 AM CEST Mauro Carvalho Chehab wrote: > Convert the PM documents to ReST, in order to allow them to > build with Sphinx. And what exactly is the motivation for doing that? There are plans for some of these files to be converted already, some of them need to be merged or split and it just is not worth it to convert some others. Thanks, Rafael
Em Tue, 16 Apr 2019 10:59:23 +0200 "Rafael J. Wysocki" <rjw@rjwysocki.net> escreveu: > On Tuesday, April 16, 2019 4:55:50 AM CEST Mauro Carvalho Chehab wrote: > > Convert the PM documents to ReST, in order to allow them to > > build with Sphinx. > > And what exactly is the motivation for doing that? Providing a little of context, I tried to submit a patchset that would just place existing documents on a sort of "staging" way, without actually reformatting: https://lkml.org/lkml/2019/4/10/244 Jon had some concerns about such approach. So, I split into one patch per subsystem. Then, I looked on each, and opted to do the conversion, as, on several cases, the conversion seemed to be easy enough. My selfish motivation is that I was returning from vacations and wanted to review some stuff at the Kernel docs, but, discovered that, despite we started migrating the documentation on May, 2016, still the vast majority of documents that weren't converted. For me, the main motivation for the conversion are: 1) Documents will be grouped into books and chapters, with makes easier to study them; 2) The Sphinx javascript is very convenient for seeking a document and a keyword within the body of the document; 3) Using a browser to read documentation allows to better scale the document to the screen I'm using. That's said, sometimes I just prefer to convert the document to a PDF and read it on my tablet. PDF tools also provide similar features. In other words, for my own consumption, I prefer reading documents using document tools, instead of reading in plain text. > There are plans for some of these files to be converted already, some of them need to be merged or split and it just is not worth it to convert some others. Feel free to use this patch as an starting point. If you prefer, I can split into smaller sets, but my main goal here is just to help to speedup the conversion. Thanks, Mauro
On Tue, Apr 16, 2019 at 12:41 PM Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote: > > Em Tue, 16 Apr 2019 10:59:23 +0200 > "Rafael J. Wysocki" <rjw@rjwysocki.net> escreveu: > > > On Tuesday, April 16, 2019 4:55:50 AM CEST Mauro Carvalho Chehab wrote: > > > Convert the PM documents to ReST, in order to allow them to > > > build with Sphinx. > > > > And what exactly is the motivation for doing that? > > Providing a little of context, I tried to submit a patchset that would > just place existing documents on a sort of "staging" way, without > actually reformatting: > > https://lkml.org/lkml/2019/4/10/244 > > Jon had some concerns about such approach. > > So, I split into one patch per subsystem. Then, I looked on each, and > opted to do the conversion, as, on several cases, the conversion > seemed to be easy enough. > > My selfish motivation is that I was returning from vacations and wanted to > review some stuff at the Kernel docs, but, discovered that, despite we > started migrating the documentation on May, 2016, still the vast > majority of documents that weren't converted. > > For me, the main motivation for the conversion are: > > 1) Documents will be grouped into books and chapters, > with makes easier to study them; > 2) The Sphinx javascript is very convenient for seeking a > document and a keyword within the body of the document; > 3) Using a browser to read documentation allows to better > scale the document to the screen I'm using. > > That's said, sometimes I just prefer to convert the document > to a PDF and read it on my tablet. PDF tools also provide > similar features. > > In other words, for my own consumption, I prefer reading > documents using document tools, instead of reading in plain > text. I see, thanks! > > There are plans for some of these files to be converted already, some of them need to be merged or split and it just is not worth it to convert some others. > > Feel free to use this patch as an starting point. If you prefer, > I can split into smaller sets, but my main goal here is just > to help to speedup the conversion. OK, we'll see. Thank you!
Jon, Em Mon, 15 Apr 2019 23:55:25 -0300 Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu: > I have a separate patch series with do the actual rename and > adjustment of references. I opted to submit this first, as it > sounds easier to merge this way, as each subsystem maintainer > can apply the conversion directly on their trees (or at docs > tree), avoiding merge conflects. Based on the number of feedbacks we have about this, I'm considering to submit a second version of my conversion patch series that would be doing the rename together with each patch, adding the rst files to an index file. However, doing that would produce lots of warnings. We have already lots of those at linux-next: checking consistency... docs/Documentation/accelerators/ocxl.rst: WARNING: document isn't included in any toctree docs/Documentation/admin-guide/mm/numaperf.rst: WARNING: document isn't included in any toctree docs/Documentation/filesystems/ext4/allocators.rst: WARNING: document isn't included in any toctree docs/Documentation/filesystems/ext4/attributes.rst: WARNING: document isn't included in any toctree docs/Documentation/filesystems/ext4/bigalloc.rst: WARNING: document isn't included in any toctree docs/Documentation/filesystems/ext4/bitmaps.rst: WARNING: document isn't included in any toctree docs/Documentation/filesystems/ext4/blockgroup.rst: WARNING: document isn't included in any toctree docs/Documentation/filesystems/ext4/blocks.rst: WARNING: document isn't included in any toctree docs/Documentation/filesystems/ext4/checksums.rst: WARNING: document isn't included in any toctree docs/Documentation/filesystems/ext4/directory.rst: WARNING: document isn't included in any toctree docs/Documentation/filesystems/ext4/eainode.rst: WARNING: document isn't included in any toctree docs/Documentation/filesystems/ext4/group_descr.rst: WARNING: document isn't included in any toctree docs/Documentation/filesystems/ext4/ifork.rst: WARNING: document isn't included in any toctree docs/Documentation/filesystems/ext4/inlinedata.rst: WARNING: document isn't included in any toctree docs/Documentation/filesystems/ext4/inodes.rst: WARNING: document isn't included in any toctree docs/Documentation/filesystems/ext4/journal.rst: WARNING: document isn't included in any toctree docs/Documentation/filesystems/ext4/mmp.rst: WARNING: document isn't included in any toctree docs/Documentation/filesystems/ext4/special_inodes.rst: WARNING: document isn't included in any toctree docs/Documentation/filesystems/ext4/super.rst: WARNING: document isn't included in any toctree docs/Documentation/fmc/index.rst: WARNING: document isn't included in any toctree docs/Documentation/gpu/msm-crash-dump.rst: WARNING: document isn't included in any toctree docs/Documentation/interconnect/interconnect.rst: WARNING: document isn't included in any toctree docs/Documentation/laptops/lg-laptop.rst: WARNING: document isn't included in any toctree docs/Documentation/virtual/kvm/amd-memory-encryption.rst: WARNING: document isn't included in any toctree docs/Documentation/virtual/kvm/vcpu-requests.rst: WARNING: document isn't included in any toctree After thinking a little bit and doing some tests, I think a good solution would be to add ":orphan:" markup to the new .rst files that were not added yet into the main body (e. g. something like the enclosed example). That will make Sphinx suppress the: "WARNING: document isn't included in any toctree" warning for the new files, while they're not included at the main indexes. This way, maintainers can do all the hard work of doing/applying the ReST file conversion/addition patch series on their own trees, and, once everything gets merged, submit a patch against the latest docs-next tree, removing the :orphan: tag and add them to the common index.rst files. That should largely avoid merging conflicts. For example, assuming that someone converts the stuff at Documentation/accounting and rename the text files there to RST (I'm actually doing that), he could add the enclosed change on the top of its index file: diff --git a/Documentation/accounting/index.rst b/Documentation/accounting/index.rst index e7dda5afa73f..e1f6284b5ff3 100644 --- a/Documentation/accounting/index.rst +++ b/Documentation/accounting/index.rst @@ -1,3 +1,5 @@ +:orphan: + ========== Accounting ========== With would make Sphinx to ignore the subdir index file while reporting errors. It will still build the documentation, allowing the developer to test the changes. One of the advantages is that checking the orphaned docs is as easy as running: $ git grep -l ":orphan:" Documentation/ ... Documentation/accounting/index.rst ... Making easy for people to check the orphaned files and send a fixup patch if something got orphaned after the merge window and send a fixes patches to be applied upstream. What do you think? Regards, Mauro
On Thu, 18 Apr 2019 09:42:23 -0300 Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote: > After thinking a little bit and doing some tests, I think a good solution > would be to add ":orphan:" markup to the new .rst files that were not > added yet into the main body (e. g. something like the enclosed example). Interesting...I didn't know about that. Yes, I think it makes sense to put that in... jon