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 __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
