[openstack-dev] [nova][docs] Concerns with docs migration

Stephen Finucane sfinucan at redhat.com
Wed Aug 2 15:22:18 UTC 2017

On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:
> Now that Stephen Finucane is back from enjoying his youth and 
> gallivanting all over Europe, and we talked about a few things in IRC 
> this morning on the docs migration for Nova, I wanted to dump my 
> concerns here for broader consumption.
> 1. We know we have to fix a bunch of broken links by adding in redirects 
> [1] which sdague started here [2]. However, that apparently didn't catch 
> everything, e.g. [3], so I'm concerned we're missing other broken links. 
> Is there a way to find out?

Manual inspection is probably the easiest way to go. 

> 2. The bottom change in the docs migration series for Nova is a massive 
> refactor of the layout of the Nova devref [4]. That's something I don't 
> want to do in Pike for two reasons:
> a) It's a huge change and we simply don't have the time to invest in 
> properly assessing and reviewing it before Pike RC1.
> b) I think that if we're going to refactor the Nova devref home page to 
> be a certain format, then we should really consider doing the same thing 
> in the other projects, because today they are all different formats 
> [5][6][7]. This is likely a cross-project discussion for the Queens PTG 
> to determine if the home page for the projects should look similar. It 
> seems they should given the uniformity that the Foundation has been 
> working toward lately.
> 3. The patch for the import of the admin guide [8] is missing some CLI 
> specific pages which are pretty useful given they aren't documented 
> anywhere else, like the forced_host part of the compute API [9]. 
> Basically anything that's cli-nova-* in the admin guide should be in the 
> Nova docs. It's also missing the compute-flavors page [10] which is 
> pretty important for using OpenStack at all.
> 4. Similar to #3, but we don't have a patch yet for importing the user 
> guide and there are several docs in the user guide that are Nova 
> specific so I'd like to make sure we include those, like [11][12].
> [1] 
> http://lists.openstack.org/pipermail/openstack-dev/2017-August/120418.html
> [2] https://review.openstack.org/#/c/489650/
> [3] https://review.openstack.org/#/c/489641/
> [4] https://review.openstack.org/#/c/478485/
> [5] https://docs.openstack.org/cinder/latest/
> [6] https://docs.openstack.org/glance/latest/
> [7] https://docs.openstack.org/neutron/latest/
> [8] https://review.openstack.org/#/c/477497/
> [9] 
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/admin-gu
> ide/source/cli-nova-specify-host.rst
> [10] 
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/admin-gu
> ide/source/compute-flavors.rst
> [11] 
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-gui
> de/source/cli-launch-instances.rst
> [12] 
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-gui
> de/source/cli-delete-an-instance.rst

More information about the OpenStack-dev mailing list