Open Stack

When we started the doc-migration projects we knew that moving all
of the content around would break a lot of external links. We said
we would deal with it if we had time at the end of the cycle. We
have put the changes into place to allow us to do that now. I'm
going to explain it here, and answer questions in this thread, and
then take the results and put them into the docs contributor guide.

1. Add a .htaccess file to your repo.

The first step is to add the configuration file Apache needs to know
what the redirect rules are, .htaccess. We have a global file in the
openstack-manuals repository but in the spirit of not making the docs
team a bottleneck for doc-related changes we have also configured
Apache to allow a .htaccess file in each project's documentation.

Sphinx needs to be told to include the file in the build output by
adding it to the list of "extra" files. This patch for nova shows
how that is done by editing doc/source/conf.py to set html_extra_path:
https://review.openstack.org/#/c/487932/5/doc/source/conf.py

If that path is set to '_extras' then the patch should also create
doc/source/_extras/.htaccess containing the redirects needed. The
contents of that file can be written by hand, or computed with a command
like:

git log --follow --name-status \
    --format='%H' origin/stable/ocata.. \
	-- doc/source | \
	grep ^R | \
	grep .rst | \
	cut -f2- | \
	sed -e 's|doc/source/|^/nova/([^/]+)/|' \
	    -e 's|doc/source/|/nova/$1/|' \
		-e 's/.rst/.html$/' \
		-e 's/.rst/.html/' \
		-e 's/^/redirectmatch 301 /'

Obviously you need to replace the 2 references to "nova" with the base
name of your git repository. The output will look something like:

redirectmatch 301 ^/nova/([^/]+)/aggregates.html$ /nova/$1/user/aggregates.html
redirectmatch 301 ^/nova/([^/]+)/architecture.html$ /nova/$1/user/architecture.html
redirectmatch 301 ^/nova/([^/]+)/block_device_mapping.html$ /nova/$1/user/block-device-mapping.html
redirectmatch 301 ^/nova/([^/]+)/cells.html$ /nova/$1/user/cells.html
redirectmatch 301 ^/nova/([^/]+)/conductor.html$ /nova/$1/user/conductor.html
redirectmatch 301 ^/nova/([^/]+)/feature_classification.html$ /nova/$1/user/feature-classification.html
redirectmatch 301 ^/nova/([^/]+)/filter_scheduler.html$ /nova/$1/user/filter-scheduler.html
redirectmatch 301 ^/nova/([^/]+)/placement.html$ /nova/$1/user/placement.html

Adding the resulting file to your repository will enable rules to
redirect from paths like /nova/latest/aggregates.html to
/nova/latest/user/aggregates.html.

2. Enable detailed redirects for your project.

The other major portion of the move that we made was to take
everything that was under /developer/$project/ and move it to
/$project/latest/ (with similar moves for other versions). By
default, any page under /developer/$project/ is now being redirected
to /$project/latest/ to at least give the user a table of contents
to find the new page. After a local .htaccess file is added to a
projects documentation we can allow /developer/$project/(.*) to
redirect to /$project/latest/$1 which will then redirect *again*
to the new home of the file.

To turn that feature on for your repository, set the has_in_tree_htaccess
flag for the repo by modifying www/project-data/latest.yaml in the
openstack-manuals repository. See
https://docs.openstack.org/contributor-guide/doc-tools/template-generator.html
for details about the other flags you can set to control how your
project appears on docs.o.o.

After the has_in_tree_htaccess flag change lands, links to URLs
like docs.openstack.org/developer/nova/cells.html should (with 2
redirects) end up at the new home
docs.openstack.org/nova/latest/user/cells.html.

Let me know if you have any questions or run into any issues making
these changes.

Doug