Re: Avoiding merge conflicts while adding new docs - Was: Re: [PATCH 00/57] Convert files to ReST
On Thu, 18 Apr 2019 09:42:23 -0300 Mauro Carvalho Chehab 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 ___ kexec mailing list kexec@lists.infradead.org http://lists.infradead.org/mailman/listinfo/kexec
Avoiding merge conflicts while adding new docs - Was: Re: [PATCH 00/57] Convert files to ReST
Jon, Em Mon, 15 Apr 2019 23:55:25 -0300 Mauro Carvalho Chehab 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
[PATCH 00/57] Convert files to ReST
This series convert lots of files to be properly parsed by Sphinx as ReST files. As it touches on lot of stuff, the series is based on linux-next. 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. Both this series and the next steps are on my devel git tree, at: https://git.linuxtv.org/mchehab/experimental.git/log/?h=all_with_indexes-v3 The final output in html can be seen at: https://www.infradead.org/~mchehab/rst_conversion/ Mauro Carvalho Chehab (57): docs: trace: fix some Sphinx warnings docs: acpi: convert text files to ReST docs: aoe: convert text files to ReST docs: arm64: convert documentation to ReST format docs: cdrom/cdrom-standard.tex: convert from LaTeX to ReST docs: cdrom: convert remaining files to ReST docs: cgroup-v1: convert to ReST file format docs: cgroup-v1/blkio-controller.rst: add a note about CFQ scheduler docs: cpu-freq: convert files to ReST docs: device-mapper: convert it to ReST format docs: extcon: move it to acpi dir and convert it to ReST docs: fault-injection: convert it to ReST format docs: fb: convert documentation to ReST format docs: fpga: convert it to ReST docs: gpio: convert it to ReST docs: ide: convert it to ReST format docs: infiniband: convert it to ReST format docs: kbuild: convert it to ReST output docs: kdump: convert it to ReST docs: livepatch: convert it to ReST format docs: locking: convert docs to ReST format docs: mic: convert it to ReST format docs: netlabel: convert it to ReST docs: pcmcia: convert it to ReST format docs: power: convert docs to ReST docs: powerpc: convert docs to ReST docs: pps/pps.txt convert it to ReST and move to API book docs: ptp.txt: convert to ReST and move to driver-api docs: riscv: convert it to ReST format docs: s390: Debugging390.txt: convert table to ascii artwork docs: s390: convert text files to ReST format s390: include/asm/debug.h add kerneldoc markups docs: serial: convert it to ReST format docs: target: convert it to ReST format docs: timers: convert documentation to ReST docs: usb: convert documents to ReST docs: watchdog: convert documents to ReST format docs: x86: convert text files to ReST docs: xilinx: convert eemi.txt to ReST docs: scheduler: convert files to ReST docs: EDID/HOWTO.txt: convert to ReST and move to kernel-API docs: connector.txt: convert to ReST docs: lcd-panel-cgram.txt convert it to ReST and move to admin-guide docs: lp855x-driver.txt: convert to ReST and move to kernel-api docs: m68k: convert it to ReST file format and add to arch bookset docs: cma/debugfs.txt: convert to ReST and move to admin-guide/mm docs: console.txt: convert to ReST format docs: pti_intel_mid.txt: convert to ReST docs: early-userspace: convert docs to ReST docs: driver-model: convert it to ReST format docs: arm: convert text files to ReST format docs: memory-devices: convert ti-emif.txt to ReST format docs: xen-tpmfront.txt: convert the file to ReST format docs: bus-devices: ti-gpmc.txt: convert it to ReST docs: nvmem: convert file to ReST format docs: phy: convert samsung-usb2.txt to ReST format docs: Prepare files to be renamed to *.rst Documentation/EDID/HOWTO.txt | 29 +- Documentation/acpi/DSD-properties-rules.txt |4 +- Documentation/acpi/acpi-lid.txt | 37 +- Documentation/acpi/aml-debugger.txt | 31 +- Documentation/acpi/apei/einj.txt | 59 +- Documentation/acpi/apei/output_format.txt | 247 +- Documentation/acpi/cppc_sysfs.txt | 52 +- Documentation/acpi/debug.txt | 20 +- .../drivers/extcon-intel-int3496.txt} | 14 +- .../acpi/dsd/data-node-references.txt | 11 +- Documentation/acpi/dsd/graph.txt | 24 +- Documentation/acpi/dsd/leds.txt | 18 +- Documentation/acpi/dsdt-override.txt |4 +- Documentation/acpi/enumeration.txt| 42 +- Documentation/acpi/gpio-properties.txt| 42 +- Documentation/acpi/i2c-muxes.txt | 21 +- Documentation/acpi/initrd_table_override.txt | 90 +- Documentation/acpi/linuxized-acpica.txt | 58 +- Documentation/acpi/lpit.txt |8 +- Documentation/acpi/method-customizing.txt | 48 +- Documentation/acpi/method-tracing.txt | 132 +- Documentation/acpi/namespace.txt | 323 +- Documentation/acpi/osi.txt|3 +- Documentation/acpi/scan_handlers.txt |9 +- Documentation/acpi/ssdt-overlays.txt | 128 +- Documentation/acpi/video_extension.txt| 16 +- Documentation/aoe/aoe.txt | 63 +-