Excerpts from Doug Hellmann's message of 2017-08-01 12:29:38 -0400: > 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.
I should add that we *only* allow Redirect and RedirectMatch rules in these files, and that we are relying on review teams to avoid adding rules that break access to their docs or redirect off-site. Reviewers, please, be careful. Doug > > 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: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev