linux-doc.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* "staging" area for unsorted random files under Documentation/*.rst
@ 2020-02-18 10:32 Mauro Carvalho Chehab
  2020-02-18 12:26 ` Jani Nikula
  0 siblings, 1 reply; 5+ messages in thread
From: Mauro Carvalho Chehab @ 2020-02-18 10:32 UTC (permalink / raw)
  To: Jonathan Corbet; +Cc: Linux Doc Mailing List

Hi Jon,

We already discussed this matter previously, but we end not doing any changes
yet.

I'm about to finish the conversion of the remaining text files to ReST.
Skipping translations and a few exceptions, after my patch series
(pending merge), there are now only ~50 remaining files[1].

Yet, we still have ~80 files already converted but not renamed, as
Documentation/*.txt files.

Shifting those around is not easy (I tried a few times), as some discussions
are required in order to get them at their rightful places.

So, my current proposal is to just rename them to *.rst, keeping them
where they are, and adding them into an "staging" area at the main
index.rst. See the enclosed patch.

Then, once we finish the conversion, we may come up with some patches
moving them to better places.

What do you think?

[1] considering my tree (based on next-20200217) at:

	https://git.linuxtv.org/mchehab/experimental.git/log/?h=all_docs_merged

	HTML output: https://www.infradead.org/~mchehab/kernel_docs/

And running this small script that should get rid of (most) false positives:

$ dirname $(find Documentation/ -type f|grep -vE '\.(rst|svg|dot|py|awk|sh|pl|gitignore|S|yaml|c|inf|vim|modes)'|grep -vE '(Makefile|Kconfig|LICENSE|COPYING-logo|ChangeLog|CREDITS)'|grep -v devicetree/bindings|grep -vE 'Documentation/(ABI|features|output|SubmittingPatches|CodingStyle|logo.gif|dontdiff|sphinx/requirements.txt|admin-guide/kdump/gdbmacros.txt|admin-guide/aoe/udev.txt|EDID/hex|netlabel/draft-ietf-cipso-ipsecurity-01.txt|firmware_class/hotplug-script|target/target-export-device|networking/mac80211-auth-assoc-deauth.txt|sparc/oradax/dax-hv-api.txt)'|grep -v translations)|sort|uniq -c|sort -n
$ echo -n "Total: "
$ dirname $(find Documentation/ -type f|grep -vE '\.(rst|svg|dot|py|awk|sh|pl|gitignore|S|yaml|c|inf|vim|modes)'|grep -vE '(Makefile|Kconfig|LICENSE|COPYING-logo|ChangeLog|CREDITS)'|grep -v devicetree/bindings|grep -vE 'Documentation/(ABI|features|output|SubmittingPatches|CodingStyle|logo.gif|dontdiff|sphinx/requirements.txt|admin-guide/kdump/gdbmacros.txt|admin-guide/aoe/udev.txt|EDID/hex|netlabel/draft-ietf-cipso-ipsecurity-01.txt|firmware_class/hotplug-script|target/target-export-device|networking/mac80211-auth-assoc-deauth.txt|sparc/oradax/dax-hv-api.txt)'|grep -v translations)|wc -l

      1 Documentation/filesystems/cifs
      1 Documentation/filesystems/configfs
      1 Documentation/scsi
      1 Documentation/virt/kvm/devices
      2 Documentation/admin-guide
      3 Documentation
      6 Documentation/devicetree
      6 Documentation/filesystems/caching
      8 Documentation/RCU
     21 Documentation/filesystems
Total: 50

Once we get this series merged, I'm planning to prepare and submit a second
series doing the conversion for the other ~20 filesystem files.

Btw, if you want to look how things will become after my patch series,
I'm keeping a html build after all my patch series at:

	https://www.infradead.org/~mchehab/kernel_docs/

Cheers,
Mauro

docs: place random ReST files at the index.rst
    
There are several ReST documents that are currently at the main
Documentation/ directory, with .txt extension.
    
That's bad, because:
    
- It is a bad example: people keep adding new .txt files
  inside Documentation/;
- Any efforts of detecting files that still require conversion
  would need to explicitly exclude those.
    
While not ideal, for now let's just place those files on
some place inside index.rst. We can later move them to
other places.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

diff --git a/Documentation/index.rst b/Documentation/index.rst
index e99d0bd2589d..9a512600c95c 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -186,6 +186,53 @@ Translations
 
    translations/index
 
+Unsorted random documents
+-------------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   DMA-API
+   DMA-API-HOWTO
+   DMA-ISA-LPC
+   DMA-attributes
+   IPMI
+   IRQ
+   IRQ-affinity
+   IRQ-domain
+   bus-virt-phys-mapping
+   crc32
+   debugging-modules
+   debugging-via-ohci1394
+   digsig
+   futex-requeue-pi
+   hwspinlock
+   io-mapping
+   io_ordering
+   irqflags-tracing
+   kobject
+   kprobes
+   kref
+   lzo
+   mailbox
+   nommu-mmap
+   percpu-rw-semaphore
+   pi-futex
+   preempt-locking
+   rbtree
+   remoteproc
+   robust-futex-ABI
+   robust-futexes
+   rpmsg
+   speculation
+   static-keys
+   tee
+   this_cpu_ops
+   unaligned-memory-access
+   watch_queue
+   xz
+
+
 Indices and tables
 ==================
 
diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.rst
similarity index 100%
rename from Documentation/DMA-API-HOWTO.txt
rename to Documentation/DMA-API-HOWTO.rst
diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.rst
similarity index 100%
rename from Documentation/DMA-API.txt
rename to Documentation/DMA-API.rst
diff --git a/Documentation/DMA-ISA-LPC.txt b/Documentation/DMA-ISA-LPC.rst
similarity index 100%
rename from Documentation/DMA-ISA-LPC.txt
rename to Documentation/DMA-ISA-LPC.rst
diff --git a/Documentation/DMA-attributes.txt b/Documentation/DMA-attributes.rst
similarity index 100%
rename from Documentation/DMA-attributes.txt
rename to Documentation/DMA-attributes.rst
diff --git a/Documentation/IPMI.txt b/Documentation/IPMI.rst
similarity index 100%
rename from Documentation/IPMI.txt
rename to Documentation/IPMI.rst
diff --git a/Documentation/IRQ-affinity.txt b/Documentation/IRQ-affinity.rst
similarity index 100%
rename from Documentation/IRQ-affinity.txt
rename to Documentation/IRQ-affinity.rst
diff --git a/Documentation/IRQ-domain.txt b/Documentation/IRQ-domain.rst
similarity index 100%
rename from Documentation/IRQ-domain.txt
rename to Documentation/IRQ-domain.rst
diff --git a/Documentation/IRQ.txt b/Documentation/IRQ.rst
similarity index 100%
rename from Documentation/IRQ.txt
rename to Documentation/IRQ.rst
diff --git a/Documentation/bus-virt-phys-mapping.txt b/Documentation/bus-virt-phys-mapping.rst
similarity index 100%
rename from Documentation/bus-virt-phys-mapping.txt
rename to Documentation/bus-virt-phys-mapping.rst
diff --git a/Documentation/crc32.txt b/Documentation/crc32.rst
similarity index 100%
rename from Documentation/crc32.txt
rename to Documentation/crc32.rst
diff --git a/Documentation/debugging-modules.txt b/Documentation/debugging-modules.rst
similarity index 100%
rename from Documentation/debugging-modules.txt
rename to Documentation/debugging-modules.rst
diff --git a/Documentation/debugging-via-ohci1394.txt b/Documentation/debugging-via-ohci1394.rst
similarity index 100%
rename from Documentation/debugging-via-ohci1394.txt
rename to Documentation/debugging-via-ohci1394.rst
diff --git a/Documentation/digsig.txt b/Documentation/digsig.rst
similarity index 100%
rename from Documentation/digsig.txt
rename to Documentation/digsig.rst
diff --git a/Documentation/futex-requeue-pi.txt b/Documentation/futex-requeue-pi.rst
similarity index 100%
rename from Documentation/futex-requeue-pi.txt
rename to Documentation/futex-requeue-pi.rst
diff --git a/Documentation/hwspinlock.txt b/Documentation/hwspinlock.rst
similarity index 100%
rename from Documentation/hwspinlock.txt
rename to Documentation/hwspinlock.rst
diff --git a/Documentation/io-mapping.txt b/Documentation/io-mapping.rst
similarity index 100%
rename from Documentation/io-mapping.txt
rename to Documentation/io-mapping.rst
diff --git a/Documentation/io_ordering.txt b/Documentation/io_ordering.rst
similarity index 100%
rename from Documentation/io_ordering.txt
rename to Documentation/io_ordering.rst
diff --git a/Documentation/irqflags-tracing.txt b/Documentation/irqflags-tracing.rst
similarity index 100%
rename from Documentation/irqflags-tracing.txt
rename to Documentation/irqflags-tracing.rst
diff --git a/Documentation/kobject.txt b/Documentation/kobject.rst
similarity index 100%
rename from Documentation/kobject.txt
rename to Documentation/kobject.rst
diff --git a/Documentation/kprobes.txt b/Documentation/kprobes.rst
similarity index 100%
rename from Documentation/kprobes.txt
rename to Documentation/kprobes.rst
diff --git a/Documentation/kref.txt b/Documentation/kref.rst
similarity index 100%
rename from Documentation/kref.txt
rename to Documentation/kref.rst
diff --git a/Documentation/lzo.txt b/Documentation/lzo.rst
similarity index 100%
rename from Documentation/lzo.txt
rename to Documentation/lzo.rst
diff --git a/Documentation/mailbox.txt b/Documentation/mailbox.rst
similarity index 100%
rename from Documentation/mailbox.txt
rename to Documentation/mailbox.rst
diff --git a/Documentation/nommu-mmap.txt b/Documentation/nommu-mmap.rst
similarity index 100%
rename from Documentation/nommu-mmap.txt
rename to Documentation/nommu-mmap.rst
diff --git a/Documentation/percpu-rw-semaphore.txt b/Documentation/percpu-rw-semaphore.rst
similarity index 100%
rename from Documentation/percpu-rw-semaphore.txt
rename to Documentation/percpu-rw-semaphore.rst
diff --git a/Documentation/pi-futex.txt b/Documentation/pi-futex.rst
similarity index 100%
rename from Documentation/pi-futex.txt
rename to Documentation/pi-futex.rst
diff --git a/Documentation/preempt-locking.txt b/Documentation/preempt-locking.rst
similarity index 100%
rename from Documentation/preempt-locking.txt
rename to Documentation/preempt-locking.rst
diff --git a/Documentation/rbtree.txt b/Documentation/rbtree.rst
similarity index 100%
rename from Documentation/rbtree.txt
rename to Documentation/rbtree.rst
diff --git a/Documentation/remoteproc.txt b/Documentation/remoteproc.rst
similarity index 100%
rename from Documentation/remoteproc.txt
rename to Documentation/remoteproc.rst
diff --git a/Documentation/robust-futex-ABI.txt b/Documentation/robust-futex-ABI.rst
similarity index 100%
rename from Documentation/robust-futex-ABI.txt
rename to Documentation/robust-futex-ABI.rst
diff --git a/Documentation/robust-futexes.txt b/Documentation/robust-futexes.rst
similarity index 100%
rename from Documentation/robust-futexes.txt
rename to Documentation/robust-futexes.rst
diff --git a/Documentation/rpmsg.txt b/Documentation/rpmsg.rst
similarity index 100%
rename from Documentation/rpmsg.txt
rename to Documentation/rpmsg.rst
diff --git a/Documentation/speculation.txt b/Documentation/speculation.rst
similarity index 100%
rename from Documentation/speculation.txt
rename to Documentation/speculation.rst
diff --git a/Documentation/static-keys.txt b/Documentation/static-keys.rst
similarity index 100%
rename from Documentation/static-keys.txt
rename to Documentation/static-keys.rst
diff --git a/Documentation/tee.txt b/Documentation/tee.rst
similarity index 100%
rename from Documentation/tee.txt
rename to Documentation/tee.rst
diff --git a/Documentation/this_cpu_ops.txt b/Documentation/this_cpu_ops.rst
similarity index 100%
rename from Documentation/this_cpu_ops.txt
rename to Documentation/this_cpu_ops.rst
diff --git a/Documentation/unaligned-memory-access.txt b/Documentation/unaligned-memory-access.rst
similarity index 100%
rename from Documentation/unaligned-memory-access.txt
rename to Documentation/unaligned-memory-access.rst
diff --git a/Documentation/xz.txt b/Documentation/xz.rst
similarity index 100%
rename from Documentation/xz.txt
rename to Documentation/xz.rst

^ permalink raw reply related	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2020-02-22  8:41 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-02-18 10:32 "staging" area for unsorted random files under Documentation/*.rst Mauro Carvalho Chehab
2020-02-18 12:26 ` Jani Nikula
2020-02-19  9:29   ` Jonathan Corbet
2020-02-20  5:29     ` Mauro Carvalho Chehab
2020-02-22  8:41       ` Mauro Carvalho Chehab

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).