Generic Linux architectural discussions
 help / color / mirror / Atom feed
* [PATCH RFC 0/2] Begin reorganizing the arch documentation
@ 2023-03-15 21:15 Jonathan Corbet
  2023-03-15 21:15 ` [PATCH 1/2] docs: create a top-level arch/ directory Jonathan Corbet
                   ` (2 more replies)
  0 siblings, 3 replies; 10+ messages in thread
From: Jonathan Corbet @ 2023-03-15 21:15 UTC (permalink / raw)
  To: linux-doc
  Cc: linux-kernel, linux-arch, Thomas Gleixner, Ingo Molnar,
	Dave Hansen, x86, Peter Zijlstra, Borislav Petkov

This two-patch series is a bare beginning of a project to reorganize the
Documentation directory somewhat; it's a toe in the water to see how many
sharks chomp at it.

The top-level Documentation/ directory, despite the efforts of the last few
years, is still a mess; there is too much stuff there, making it harder to
find anything.  We do not organize our source directories that way, and for
good reasons.

To bring the docs closer to the source organization, create a directory
Documentation/arch and move the x86 docs there, updating all of the
internal references that are broken by the move.  The appearance of the
rendered documentation does not change.  I've deliberately not changed
any overly long lines generated to keep the diff easy to read; that can
be fixed up later if warranted.

I can also break the second patch up if maintainers want to handle pieces
of it separately.

I think this move is worthwhile (for the other arches too) because it will
make our documentation better organized in a way that matches the source
and easier to navigate.  It will also make easier to experiment with tools
like intersphinx.

On the other hand, it *is* a fair amount of churn.  If it's more than
people can handle, I'll quietly back away and we'll muddle along as we have
been; this isn't something I'm going to dig in my heels over.

Also, it is worth noting that, while the rendered HTML looks the same,
links that went to Documentation/x86 (on https://kernel.org, say) will be
broken by this change.  We have never considered whether we care about
preserving external links to the rendered docs on kernel.org or not; I
don't think we should break them without thinking about it.

Thoughts?

Thanks,

jon


Jonathan Corbet (2):
  docs: create a top-level arch/ directory
  docs: move x86 documentation into Documentation/arch/

 Documentation/admin-guide/hw-vuln/mds.rst     |  2 +-
 .../admin-guide/hw-vuln/tsx_async_abort.rst   |  2 +-
 .../admin-guide/kernel-parameters.rst         |  6 ++--
 .../admin-guide/kernel-parameters.txt         |  8 +++---
 Documentation/admin-guide/ras.rst             |  2 +-
 Documentation/admin-guide/sysctl/kernel.rst   |  4 +--
 Documentation/arch.rst                        | 28 -------------------
 Documentation/arch/index.rst                  | 28 +++++++++++++++++++
 .../{ => arch}/x86/amd-memory-encryption.rst  |  0
 Documentation/{ => arch}/x86/amd_hsmp.rst     |  0
 Documentation/{ => arch}/x86/boot.rst         |  4 +--
 Documentation/{ => arch}/x86/booting-dt.rst   |  2 +-
 Documentation/{ => arch}/x86/buslock.rst      |  0
 Documentation/{ => arch}/x86/cpuinfo.rst      |  0
 Documentation/{ => arch}/x86/earlyprintk.rst  |  0
 Documentation/{ => arch}/x86/elf_auxvec.rst   |  0
 Documentation/{ => arch}/x86/entry_64.rst     |  0
 .../{ => arch}/x86/exception-tables.rst       |  0
 Documentation/{ => arch}/x86/features.rst     |  0
 Documentation/{ => arch}/x86/i386/IO-APIC.rst |  0
 Documentation/{ => arch}/x86/i386/index.rst   |  0
 Documentation/{ => arch}/x86/ifs.rst          |  0
 Documentation/{ => arch}/x86/index.rst        |  0
 Documentation/{ => arch}/x86/intel-hfi.rst    |  0
 Documentation/{ => arch}/x86/intel_txt.rst    |  0
 Documentation/{ => arch}/x86/iommu.rst        |  0
 .../{ => arch}/x86/kernel-stacks.rst          |  0
 Documentation/{ => arch}/x86/mds.rst          |  0
 Documentation/{ => arch}/x86/microcode.rst    |  0
 Documentation/{ => arch}/x86/mtrr.rst         |  2 +-
 Documentation/{ => arch}/x86/orc-unwinder.rst |  0
 Documentation/{ => arch}/x86/pat.rst          |  0
 Documentation/{ => arch}/x86/pti.rst          |  0
 Documentation/{ => arch}/x86/resctrl.rst      |  0
 Documentation/{ => arch}/x86/sgx.rst          |  0
 Documentation/{ => arch}/x86/sva.rst          |  0
 Documentation/{ => arch}/x86/tdx.rst          |  0
 Documentation/{ => arch}/x86/tlb.rst          |  0
 Documentation/{ => arch}/x86/topology.rst     |  0
 .../{ => arch}/x86/tsx_async_abort.rst        |  0
 .../{ => arch}/x86/usb-legacy-support.rst     |  0
 .../{ => arch}/x86/x86_64/5level-paging.rst   |  2 +-
 .../{ => arch}/x86/x86_64/boot-options.rst    |  4 +--
 .../x86/x86_64/cpu-hotplug-spec.rst           |  0
 .../x86/x86_64/fake-numa-for-cpusets.rst      |  2 +-
 Documentation/{ => arch}/x86/x86_64/fsgs.rst  |  0
 Documentation/{ => arch}/x86/x86_64/index.rst |  0
 .../{ => arch}/x86/x86_64/machinecheck.rst    |  0
 Documentation/{ => arch}/x86/x86_64/mm.rst    |  0
 Documentation/{ => arch}/x86/x86_64/uefi.rst  |  0
 Documentation/{ => arch}/x86/xstate.rst       |  0
 Documentation/{ => arch}/x86/zero-page.rst    |  0
 Documentation/core-api/asm-annotations.rst    |  2 +-
 Documentation/driver-api/device-io.rst        |  2 +-
 Documentation/index.rst                       |  2 +-
 Documentation/virt/kvm/api.rst                |  2 +-
 MAINTAINERS                                   | 12 ++++----
 arch/arm/Kconfig                              |  2 +-
 arch/x86/Kconfig                              | 10 +++----
 arch/x86/Kconfig.debug                        |  2 +-
 arch/x86/boot/header.S                        |  2 +-
 arch/x86/entry/entry_64.S                     |  2 +-
 arch/x86/include/asm/bootparam_utils.h        |  2 +-
 arch/x86/include/asm/page_64_types.h          |  2 +-
 arch/x86/include/asm/pgtable_64_types.h       |  2 +-
 arch/x86/kernel/cpu/microcode/amd.c           |  2 +-
 arch/x86/kernel/cpu/resctrl/monitor.c         |  2 +-
 arch/x86/kernel/cpu/sgx/sgx.h                 |  2 +-
 arch/x86/kernel/kexec-bzimage64.c             |  2 +-
 arch/x86/kernel/pci-dma.c                     |  2 +-
 arch/x86/mm/pat/set_memory.c                  |  2 +-
 arch/x86/mm/tlb.c                             |  2 +-
 arch/x86/platform/pvh/enlighten.c             |  2 +-
 drivers/vhost/vhost.c                         |  2 +-
 security/Kconfig                              |  2 +-
 tools/include/linux/err.h                     |  2 +-
 tools/objtool/Documentation/objtool.txt       |  2 +-
 77 files changed, 82 insertions(+), 82 deletions(-)
 delete mode 100644 Documentation/arch.rst
 create mode 100644 Documentation/arch/index.rst
 rename Documentation/{ => arch}/x86/amd-memory-encryption.rst (100%)
 rename Documentation/{ => arch}/x86/amd_hsmp.rst (100%)
 rename Documentation/{ => arch}/x86/boot.rst (99%)
 rename Documentation/{ => arch}/x86/booting-dt.rst (96%)
 rename Documentation/{ => arch}/x86/buslock.rst (100%)
 rename Documentation/{ => arch}/x86/cpuinfo.rst (100%)
 rename Documentation/{ => arch}/x86/earlyprintk.rst (100%)
 rename Documentation/{ => arch}/x86/elf_auxvec.rst (100%)
 rename Documentation/{ => arch}/x86/entry_64.rst (100%)
 rename Documentation/{ => arch}/x86/exception-tables.rst (100%)
 rename Documentation/{ => arch}/x86/features.rst (100%)
 rename Documentation/{ => arch}/x86/i386/IO-APIC.rst (100%)
 rename Documentation/{ => arch}/x86/i386/index.rst (100%)
 rename Documentation/{ => arch}/x86/ifs.rst (100%)
 rename Documentation/{ => arch}/x86/index.rst (100%)
 rename Documentation/{ => arch}/x86/intel-hfi.rst (100%)
 rename Documentation/{ => arch}/x86/intel_txt.rst (100%)
 rename Documentation/{ => arch}/x86/iommu.rst (100%)
 rename Documentation/{ => arch}/x86/kernel-stacks.rst (100%)
 rename Documentation/{ => arch}/x86/mds.rst (100%)
 rename Documentation/{ => arch}/x86/microcode.rst (100%)
 rename Documentation/{ => arch}/x86/mtrr.rst (99%)
 rename Documentation/{ => arch}/x86/orc-unwinder.rst (100%)
 rename Documentation/{ => arch}/x86/pat.rst (100%)
 rename Documentation/{ => arch}/x86/pti.rst (100%)
 rename Documentation/{ => arch}/x86/resctrl.rst (100%)
 rename Documentation/{ => arch}/x86/sgx.rst (100%)
 rename Documentation/{ => arch}/x86/sva.rst (100%)
 rename Documentation/{ => arch}/x86/tdx.rst (100%)
 rename Documentation/{ => arch}/x86/tlb.rst (100%)
 rename Documentation/{ => arch}/x86/topology.rst (100%)
 rename Documentation/{ => arch}/x86/tsx_async_abort.rst (100%)
 rename Documentation/{ => arch}/x86/usb-legacy-support.rst (100%)
 rename Documentation/{ => arch}/x86/x86_64/5level-paging.rst (98%)
 rename Documentation/{ => arch}/x86/x86_64/boot-options.rst (98%)
 rename Documentation/{ => arch}/x86/x86_64/cpu-hotplug-spec.rst (100%)
 rename Documentation/{ => arch}/x86/x86_64/fake-numa-for-cpusets.rst (97%)
 rename Documentation/{ => arch}/x86/x86_64/fsgs.rst (100%)
 rename Documentation/{ => arch}/x86/x86_64/index.rst (100%)
 rename Documentation/{ => arch}/x86/x86_64/machinecheck.rst (100%)
 rename Documentation/{ => arch}/x86/x86_64/mm.rst (100%)
 rename Documentation/{ => arch}/x86/x86_64/uefi.rst (100%)
 rename Documentation/{ => arch}/x86/xstate.rst (100%)
 rename Documentation/{ => arch}/x86/zero-page.rst (100%)

-- 
2.39.2


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

end of thread, other threads:[~2023-03-31  3:20 UTC | newest]

Thread overview: 10+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-03-15 21:15 [PATCH RFC 0/2] Begin reorganizing the arch documentation Jonathan Corbet
2023-03-15 21:15 ` [PATCH 1/2] docs: create a top-level arch/ directory Jonathan Corbet
2023-03-15 21:15 ` [PATCH 2/2] docs: move x86 documentation into Documentation/arch/ Jonathan Corbet
2023-03-23 19:15   ` Dave Hansen
2023-03-15 22:18 ` [PATCH RFC 0/2] Begin reorganizing the arch documentation Dave Hansen
2023-03-23 18:48   ` Jonathan Corbet
2023-03-23 19:20     ` Dave Hansen
2023-03-23 19:40       ` Jonathan Corbet
2023-03-30 18:52         ` Jonathan Corbet
2023-03-31  3:20           ` Stephen Rothwell

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox