Remove the Creating Documentation tutorial

[willingc]

This tutorial is dated. It's also not directly related to packaging. It would be better to create a new docs tutorial or refer to existing documentation in other places.

I could see a future "How to" guide about making documentation be an extra installation.

[jeanas]

Perhaps we can make the page a redirect to, e.g., https://www.sphinx-doc.org/en/master/tutorial/index.html, to avoid breaking links?

Patch:

diff --git a/requirements.txt b/requirements.txt
index d6e0d75..42fb1a1 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -5,3 +5,4 @@ python-docs-theme==2023.9
 sphinx-copybutton==0.5.0
 pypa-docs-theme @ git+https://github.com/pypa/pypa-docs-theme.git
 sphinx-toolbox==3.5.0
+sphinx-reredirects==0.1.3
diff --git a/source/conf.py b/source/conf.py
index 9113b8c..e083e7c 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -36,6 +36,7 @@ extensions = [
     'sphinx.ext.todo',
     'sphinx_inline_tabs',
     'sphinx_copybutton',
+    'sphinx_reredirects',
     'sphinx_toolbox.collapse',
 ]
 
@@ -446,3 +447,8 @@ nitpick_ignore = [
     ('py:func', 'setuptools.find_packages'),
     ('py:func', 'setuptools.setup'),
 ]
+
+# Redirects for deleted/moved pages
+redirects = {
+    "tutorials/creating-documentation": "https://www.sphinx-doc.org/en/master/tutorial",
+}

[pradyunsg]

I do agree that we should drop this page, and I also share the concern of dropping the page without redirects breaking existing links.

However, I don't like the idea of silently redirecting to another domain though -- it's a hard-coded link in source code that can't be checked for whether it is out of date automatically via Sphinx's linkcheck.

@willingc How do you feel about keeping the toctree removal and replacing page with a orphan stub page? Something like the following (wrapping where appropriate)...

:orphan:

Creating documentation
======================

This tutorial has been removed since it is not related to packaging and was unmaintained. Please see the `Sphinx tutorial <https://www.sphinx-doc.org/en/master/tutorial>`_ instead.

[willingc]

Great suggestion about the breaking links. I like the @pradyunsg's suggestion for a stub.

[sinoroc]

Even better now.

[jeanas]

documatt/sphinx-reredirects#6 😉

[pradyunsg]

Hah, nice @jeanas! ^.^