Building docs fails due to reference to nonexisting document

[Matt Riedemann]

Building docs locally fails on some contributor/api/autoindex circular reference issue (I found the circular reference by disabling warning-is-error in setup.cfg):

Warning, treated as error:
/home/user/git/cinder/doc/source/contributor/api/autoindex.rst:1:toctree contains reference to nonexisting document u'contributor/api/doc/source/api/autoindex'

user@ubuntu:~/git/cinder$ git show -1
commit 2a92448c69df1b94eec16cb24320d255c7a5c7be
Merge: bb948d8 230f6ca
Author: Jenkins <email address hidden>
Date: Mon Sep 11 09:36:03 2017 +0000

    Merge "IBM XIV: Fix ordered use of a dict"

user@ubuntu:~/git/cinder$

[Matt Riedemann (mriedem)]

There is an old cinder sphinx autodoc extension (copied from nova) which is still being used, and that might be causing some issues. I wonder if that should be removed and then do some cleanup like what I did in nova awhile ago:

https://review.openstack.org/#/c/199297/

[Sean McGinnis (sean-mcginnis)]

I am able to reproduce this failure on one of my existing cloned repo. It appears to at least partially be related to the removal of api.v1. Running the command 'find . -type f -name "*.pyc" -delete' at least got me past the v1 error on to another stale reference.

Running the docs job on a freshly cloned repo ran fine. So this appears to be an issue of stale files being present in the repo.

Marking as Incomplete rather than Invalid for now because I think we need to figure out what these stale files are and how to clean them up. But this appears to be a procedural need so far rather than a code bug.

[Sean McGinnis (sean-mcginnis)]

Update title as I've seen this with various files for things that were removed or renamed. Can't find where information about these old files is cached, but a fresh clone does not have the issue, so it's definitely something to do with stale data.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/505760

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/505760
Committed: https://git.openstack.org/cgit/openstack/cinder/commit/?id=604529a1606d9698f9e6f0a978118eec5c902094
Submitter: Jenkins
Branch: master

commit 604529a1606d9698f9e6f0a978118eec5c902094
Author: Sean McGinnis <email address hidden>
Date: Wed Sep 20 12:24:44 2017 -0500

    Clear cached autogenerated docs before docs build

    Leftover data in the autogenerated docs can result in build
    failure. Remove these files before every build to be safe.

    Change-Id: Iec3ff7334b7af80cb34019590544fab0b1c95240
    Closes-bug: #1716478

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/cinder 12.0.0.0b1 development milestone.