Open Stack

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