Using stub pages to replace redirects #2147
Comments
ansible-documentation-bot
bot
added
the
needs_triage
Stubs that do not existStub pages in this section do not exist in the Getting started/ansible/(devel|latest)/intro_getting_started.html Command line tools/ansible/(devel|latest)/command_line_tools.html CLI guides/ansible/(devel|latest)/ansible.html Vault guide/ansible/(devel|latest)/playbooks_vault.html Modules and plugins/ansible/(devel|latest)/modules.html Installation guide/ansible/(devel|latest)/intro_configuration.html Inventory guide/ansible/(devel|latest)/intro_inventory.html Module list landing topics/ansible/(devel|latest)/network_maintained.html Networking guide/ansible/(devel|latest)/network_best_practices_2.5.html Plugins list/ansible/(devel|latest)/plugins.html Porting guide/ansible/(devel|latest)/porting_guide_2.0.html Reference and appendices/ansible/(devel|latest)/common_return_values.html Scenario Guides/ansible/(devel|latest)/guide_aws.html Renamed module reference directory/ansible/(devel|latest)/modules_by_category.html Community page/ansible/(devel|latest)/community.html Windows and BSD guide/ansible/(devel|latest)/windows.html Not devel or latest version filesSome files in the redirects are non-versioned or specific to older versions. /ansible/(developing_[^/]+).html Redirects a full directory/ansible/(devel|latest)/module_docs/?(.+)? Pages moved in older versions, 2.5 and 2.6/ansible/([^/]+)/user_guide/playbooks_vault.html Related to PR 74834 (link still exists in 2.9 error messages)/ansible/playbooks_vault.html Playbook guide/ansible/(devel|latest)/playbooks.html |
Stubs that already existFor completeness, here is a list of all the stub pages that already exist in the User guide/ansible/(devel|latest)/user_guide/basic_concepts.html Developer/ansible/(devel|latest)/dev_guide/testing_compile.html |
samccann
removed
DaWGs
|
@samccann Got an update on this one. We can discuss at the next DaWGs but I'll put some notes in here. I started hacking around with another sphinx extension to generate stub pages at build time. It works like this:
Here are descriptions of the fields:
The stub generator extension can go through and generate all the RST files at build time. I've got this to work but it's sort of janky. It's good because we don't need to actually create a bunch more stub files in the repo like we have in the What sucks is that the stub generator actually generates the RST files so we'd either need to add them all to Another thing that isn't great is that the resulting HTML pages have two canonical urls: The first one ( So this leaves us with two challenges to tackle:
Good newsThankfully there's already a Sphinx extension that solves most of our problems. I give you: https://pypi.org/project/sphinx-reredirects/ Using the same two examples from that sample yaml file above, it's as simple as adding this to the This results in pages under
When you attempt to access either of those pages, you get automatically redirected to the Getting Started page. It looks promising and a happy medium for us. We don't need any custom code and we can define redirects in Now I don't think this is the absolute best for SEO. As the FAQ page points out, 301 redirects are preferable. At the same time, these redirects are much better than 404 pages. It also looks super promising because that extension supports wildcards so we can redirect full directories and potentially some of the consolidated redirects from older versions, instead of relying on a limited number of Read The Docs redirects which might be tricky to set up for subprojects. |
This issue outlines a plan to replace redirects from
.htaccessconfiguration files in the ansible/docsite repository with stub pages.The purpose of this plan is to facilitate the migration of Ansible community documentation from Red Hat managed infrastructure to Read The Docs hosting. Redirects are created when pages move to avoid 404 errors. However we have more redirects now than we can add to projects on Read The Docs.
Stub pages
Stub pages are RST files that use the
orphanmetadata field so that the page is generated at build time but not included in the toctree. The result is that the stub page does not appear in the navigation or documentation structure, while still being reachable from a direct external link such as a bookmark or reference in a third-party site.Stub pages provide an alternative to dynamic HTTP redirects that prevent 404 errors and broken links. They have the following benefits:
Stub pages also have some drawbacks:
Example stub page
Here is what an RST stub page should look like:
Background
So why do we need to create stub files in the first place?
Ansible community documentation that is available from
docs.ansible.comhas long been hosted on Red Hat managed infrastructure. This infrastructue includes Apache httpd services with themod_rewritemodule that provides dynamic redirect functionality. When pages in the Ansible package documentation were relocated or removed, a redirect rule was added to the.htaccessconfiguration file. These files are sourced in the ansible/docsite repository.To migrate hosting to ReadTheDocs, and provide greater access to community maintainers, a strategy is needed to prevent broken redirects that would result in 404s and degradation of SEO authority. We can create some redirects in the ReadTheDocs project but there is a limit of 100 redirects per project.
Unfortunately the number of existing redirects already exceeds that limit. For moved pages alone, we have more than 200 redirects. Read The Docs imposes a limi of 100 redirects per project.
Additionally, a goal is to move away from creating redirects because this adds a lot of maintenance overhead to the project. The reasoning for the creation of many of the redirect rules in the
.htaccessconfiguration files is historical knowledge with little no documentation.Looking in the
.htaccessfile you can see rules such as this one:When we migrate the
docs.ansible.comsubdomain to Read The Docs hosting, we can update these redirects to point to the new project as follows:This redirect works for any links that are internal to the Ansible community documentation. For instance, if a page references
user_guide/playbooks_blocks.htmlthe redirect will point to the corresponding page on ReadTheDocs.However, if there is an external link such as a bookmark or reference from a third-party site, the redirect does not take effect because the
docs.ansible.comsubdomain has moved to ReadTheDocs.In other words, the following page will not be on Read The Docs and the redirect does not take effect because
docs.ansible.comis served by Read The Docs:https://docs.ansible.com/ansible/latest/user_guide/playbooks_blocks.html
As a result, any external link that points to that page will cause a 404 error.
Stub pages on Read The Docs
One thing to note is that, as long as
docs.ansible.comis on Red Hat managed infrastructure, we can keep the redirects in place. We do want to create all the stub pages before we migrate the subdomain over to RTD but they don't really serve a purpose until after the migration.On ReadTheDocs we will have a top-level redirect in place that handles the new URL structure with the
/projects/subfolder:Here is how that top-level redirect will work:
In this case, the stub page is in place for the target url. You can actually view the user_guide/playbooks_blocks.html stub page on ReadTheDocs today.
We created that stub page when we restructured the user guide. We also created the redirects for
docs.ansible.combut, again, we won't be moving the redirects over to Read The Docs because there are too many.The text was updated successfully, but these errors were encountered: