linux-ia64.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Costa Shulyupin <costa.shul@redhat.com>
To: Jonathan Corbet <corbet@lwn.net>,
	Mauro Carvalho Chehab <mchehab@kernel.org>,
	linux-doc@vger.kernel.org
Cc: Costa Shulyupin <costa.shul@redhat.com>,
	Vineet Gupta <vgupta@kernel.org>, Jonas Bonn <jonas@southpole.se>,
	Stefan Kristiansson <stefan.kristiansson@saunalahti.fi>,
	Stafford Horne <shorne@gmail.com>,
	"James E.J. Bottomley" <James.Bottomley@HansenPartnership.com>,
	Helge Deller <deller@gmx.de>,
	Yoshinori Sato <ysato@users.sourceforge.jp>,
	Rich Felker <dalias@libc.org>,
	John Paul Adrian Glaubitz <glaubitz@physik.fu-berlin.de>,
	Thomas Gleixner <tglx@linutronix.de>,
	Ingo Molnar <mingo@redhat.com>, Borislav Petkov <bp@alien8.de>,
	Dave Hansen <dave.hansen@linux.intel.com>,
	"maintainer:X86 ARCHITECTURE 32-BIT AND 64-BIT" <x86@kernel.org>,
	"H. Peter Anvin" <hpa@zytor.com>,
	Yanteng Si <siyanteng@loongson.cn>,
	Geert Uytterhoeven <geert@linux-m68k.org>,
	Max Filippov <jcmvbkbc@gmail.com>,
	"open list:SYNOPSYS ARC ARCHITECTURE"
	<linux-snps-arc@lists.infradead.org>,
	open list <linux-kernel@vger.kernel.org>,
	"open list:IA64 Itanium PLATFORM" <linux-ia64@vger.kernel.org>,
	"open list:OPENRISC ARCHITECTURE"
	<linux-openrisc@vger.kernel.org>,
	"open list:PARISC ARCHITECTURE" <linux-parisc@vger.kernel.org>,
	"open list:SUPERH" <linux-sh@vger.kernel.org>
Subject: [PATCH v3] docs: directive `alias` for redirects
Date: Thu, 04 May 2023 18:01:52 +0000	[thread overview]
Message-ID: <20230504180210.727364-1-costa.shul@redhat.com> (raw)

and several redirects for moved main arch pages

Problems:
- The documentation lacks hierarchy
- Relocating pages disrupts external links to
  the documentation and causes confusion for users

Benefits:
- Users can easily access relocated pages from external resources
- Using redirects frees up options for reorganizing the documentation

The solution:
- Introduced directive `alias` which declares previous path of
  a moved document as the argument.
- Redirects are implemented with Sphinx extension rediraffe_redirects.

Signed-off-by: Costa Shulyupin <costa.shul@redhat.com>

---

Changes:
- complete new implementation
---
 Documentation/arch/arc/index.rst        |  2 ++
 Documentation/arch/ia64/index.rst       |  2 ++
 Documentation/arch/index.rst            |  2 ++
 Documentation/arch/m68k/index.rst       |  2 ++
 Documentation/arch/nios2/index.rst      |  2 ++
 Documentation/arch/openrisc/index.rst   |  2 ++
 Documentation/arch/parisc/index.rst     |  2 ++
 Documentation/arch/sh/index.rst         |  2 ++
 Documentation/arch/sparc/index.rst      |  2 ++
 Documentation/arch/x86/index.rst        |  2 ++
 Documentation/arch/x86/x86_64/index.rst |  2 ++
 Documentation/arch/xtensa/index.rst     |  2 ++
 Documentation/conf.py                   |  9 +++++++
 Documentation/sphinx/alias.py           | 35 +++++++++++++++++++++++++
 Documentation/sphinx/requirements.txt   |  1 +
 15 files changed, 69 insertions(+)
 create mode 100644 Documentation/sphinx/alias.py

diff --git a/Documentation/arch/arc/index.rst b/Documentation/arch/arc/index.rst
index 7b098d4a5e3e..c2be040f04c3 100644
--- a/Documentation/arch/arc/index.rst
+++ b/Documentation/arch/arc/index.rst
@@ -15,3 +15,5 @@ ARC architecture
    === 
    * :ref:`genindex`
+
+.. alias:: arc/index
diff --git a/Documentation/arch/ia64/index.rst b/Documentation/arch/ia64/index.rst
index 761f2154dfa2..c4f973f17af2 100644
--- a/Documentation/arch/ia64/index.rst
+++ b/Documentation/arch/ia64/index.rst
@@ -17,3 +17,5 @@ IA-64 Architecture
    serial
 
    features
+
+.. alias:: ia64/index
diff --git a/Documentation/arch/index.rst b/Documentation/arch/index.rst
index 80ee31016584..11be66e23de4 100644
--- a/Documentation/arch/index.rst
+++ b/Documentation/arch/index.rst
@@ -26,3 +26,5 @@ implementation.
    sparc/index
    x86/index
    xtensa/index
+
+.. alias:: arch
diff --git a/Documentation/arch/m68k/index.rst b/Documentation/arch/m68k/index.rst
index 0f890dbb5fe2..9b5c34510fb7 100644
--- a/Documentation/arch/m68k/index.rst
+++ b/Documentation/arch/m68k/index.rst
@@ -18,3 +18,5 @@ m68k Architecture
    === 
    * :ref:`genindex`
+
+.. alias:: m68k/index
diff --git a/Documentation/arch/nios2/index.rst b/Documentation/arch/nios2/index.rst
index 4468fe1a1037..bfaf0e963db3 100644
--- a/Documentation/arch/nios2/index.rst
+++ b/Documentation/arch/nios2/index.rst
@@ -10,3 +10,5 @@ Nios II Specific Documentation
 
    nios2
    features
+
+.. alias:: nios2/index
diff --git a/Documentation/arch/openrisc/index.rst b/Documentation/arch/openrisc/index.rst
index 6879f998b87a..b59d97d6f8b7 100644
--- a/Documentation/arch/openrisc/index.rst
+++ b/Documentation/arch/openrisc/index.rst
@@ -18,3 +18,5 @@ OpenRISC Architecture
    === 
    * :ref:`genindex`
+
+.. alias:: openrisc/index
diff --git a/Documentation/arch/parisc/index.rst b/Documentation/arch/parisc/index.rst
index 240685751825..aaa708c7f98d 100644
--- a/Documentation/arch/parisc/index.rst
+++ b/Documentation/arch/parisc/index.rst
@@ -18,3 +18,5 @@ PA-RISC Architecture
    === 
    * :ref:`genindex`
+
+.. alias:: parisc/index
diff --git a/Documentation/arch/sh/index.rst b/Documentation/arch/sh/index.rst
index c64776738cf6..5a12d76abec4 100644
--- a/Documentation/arch/sh/index.rst
+++ b/Documentation/arch/sh/index.rst
@@ -54,3 +54,5 @@ Maple
 
 .. kernel-doc:: drivers/sh/maple/maple.c
    :export:
+
+.. alias:: sh/index
diff --git a/Documentation/arch/sparc/index.rst b/Documentation/arch/sparc/index.rst
index ae884224eec2..f2731a4925c3 100644
--- a/Documentation/arch/sparc/index.rst
+++ b/Documentation/arch/sparc/index.rst
@@ -11,3 +11,5 @@ Sparc Architecture
    oradax/oracle-dax
 
    features
+
+.. alias:: sparc/index
diff --git a/Documentation/arch/x86/index.rst b/Documentation/arch/x86/index.rst
index c73d133fd37c..2154bfe2b6ca 100644
--- a/Documentation/arch/x86/index.rst
+++ b/Documentation/arch/x86/index.rst
@@ -42,3 +42,5 @@ x86-specific Documentation
    features
    elf_auxvec
    xstate
+
+.. alias:: x86/index
diff --git a/Documentation/arch/x86/x86_64/index.rst b/Documentation/arch/x86/x86_64/index.rst
index a56070fc8e77..d4eb610b0080 100644
--- a/Documentation/arch/x86/x86_64/index.rst
+++ b/Documentation/arch/x86/x86_64/index.rst
@@ -15,3 +15,5 @@ x86_64 Support
    cpu-hotplug-spec
    machinecheck
    fsgs
+
+.. alias:: x86/x86_64/index
diff --git a/Documentation/arch/xtensa/index.rst b/Documentation/arch/xtensa/index.rst
index 69952446a9be..a794bddddad4 100644
--- a/Documentation/arch/xtensa/index.rst
+++ b/Documentation/arch/xtensa/index.rst
@@ -12,3 +12,5 @@ Xtensa Architecture
    mmu
 
    features
+
+.. alias:: xtensa/index
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 37314afd1ac8..068f85e5dd1f 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -16,6 +16,7 @@ import sys
 import os
 import sphinx
 import shutil
+from importlib.util import find_spec
 
 # helper
 # ------
@@ -57,6 +58,14 @@ extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
               'maintainers_include', 'sphinx.ext.autosectionlabel',
               'kernel_abi', 'kernel_feat']
 
+extensions += ['alias'] # uses rediraffe
+
+if find_spec('sphinxext.rediraffe'):
+    extensions += ['sphinxext.rediraffe']
+    rediraffe_redirects = { }
+else:
+    print("Skipping redirects because sphinxext.rediraffe is not installed")
+
 if major >= 3:
     if (major > 3) or (minor > 0 or patch >= 2):
         # Sphinx c function parser is more pedantic with regards to type
diff --git a/Documentation/sphinx/alias.py b/Documentation/sphinx/alias.py
new file mode 100644
index 000000000000..e00605d07dbd
--- /dev/null
+++ b/Documentation/sphinx/alias.py
@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: GPL-2.0
+
+u"""
+    Directive `alias`
+    ~~~~~~~~~~~~~~~
+    Provides browser redirects for moved pages.
+
+    The directive declares previous path of a moved document as the argument.
+    Redirects are implemented with Sphinx extension rediraffe_redirects.
+
+    :copyright: Copyright 2023 Costa Shulyupin <costa.shul@redhat.com>
+    :license:   GPL Version 2, June 1991 see linux/COPYING for details.
+
+"""
+
+from docutils.parsers.rst import Directive
+import os
+
+
+class AliasDirective(Directive):
+    required_arguments = 1
+
+    def run(self):
+        env = self.state.document.settings.env
+        if 'rediraffe_redirects' not in env.config:
+            return []
+        env.config.rediraffe_redirects[self.arguments[0]] \
+            = os.path.relpath(self.state.document.current_source,
+                              env.srcdir)
+        return []
+
+
+def setup(app):
+    app.add_directive('alias', AliasDirective)
+    return { 'parallel_read_safe': False, 'parallel_write_safe': False }
diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
index 335b53df35e2..9ff99beb5ed3 100644
--- a/Documentation/sphinx/requirements.txt
+++ b/Documentation/sphinx/requirements.txt
@@ -1,3 +1,4 @@
 # jinja2>=3.1 is not compatible with Sphinx<4.0
 jinja2<3.1
 Sphinx=2.4.4
+rediraffe_redirects
-- 
2.40.0

             reply	other threads:[~2023-05-04 18:01 UTC|newest]

Thread overview: 2+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2023-05-04 18:01 Costa Shulyupin [this message]
2023-05-04 18:41 ` [PATCH v3] docs: directive `alias` for redirects Jonathan Corbet

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20230504180210.727364-1-costa.shul@redhat.com \
    --to=costa.shul@redhat.com \
    --cc=James.Bottomley@HansenPartnership.com \
    --cc=bp@alien8.de \
    --cc=corbet@lwn.net \
    --cc=dalias@libc.org \
    --cc=dave.hansen@linux.intel.com \
    --cc=deller@gmx.de \
    --cc=geert@linux-m68k.org \
    --cc=glaubitz@physik.fu-berlin.de \
    --cc=hpa@zytor.com \
    --cc=jcmvbkbc@gmail.com \
    --cc=jonas@southpole.se \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-ia64@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-openrisc@vger.kernel.org \
    --cc=linux-parisc@vger.kernel.org \
    --cc=linux-sh@vger.kernel.org \
    --cc=linux-snps-arc@lists.infradead.org \
    --cc=mchehab@kernel.org \
    --cc=mingo@redhat.com \
    --cc=shorne@gmail.com \
    --cc=siyanteng@loongson.cn \
    --cc=stefan.kristiansson@saunalahti.fi \
    --cc=tglx@linutronix.de \
    --cc=vgupta@kernel.org \
    --cc=x86@kernel.org \
    --cc=ysato@users.sourceforge.jp \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
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 read-only IMAP folder(s) and NNTP newsgroup(s).