Building contributor documentation is broken

[Ana Krivokapić]

Following the steps listed at https://github.com/openstack/horizon#building-contributor-documentation to build the contributor documentation.

1) Building automatically, using ./run_tests.sh --docs fails with ImportErrors and AttributeErrors (see attached file for details).

2) Building manually refers to non-existent file generate_autodoc_index.py. Moreover, setting the env var DJANGO_SETTINGS_MODULE has no effect as the scripts later override it (it is hardcoded to openstack_dashboard.settings in both run_tests.sh and doc/source/conf.py).

[OpenStack Infra (hudson-openstack)]

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

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/62980
Committed: https://git.openstack.org/cgit/openstack/horizon/commit/?id=1880fd63aa5f99e316deb231a13d853128a89c4f
Submitter: Jenkins
Branch: master

commit 1880fd63aa5f99e316deb231a13d853128a89c4f
Author: Facundo Maldonado <email address hidden>
Date: Mon Dec 16 14:16:44 2013 -0300

    Fixed sphinx ERRORs.

    Fixed errors and warnings due to formatting and layout errors
    in documentation.
    Those errors makes the page be empty or unavailable.
    Other layouts/format fixes makes documentation more clear.

    Removed rpc/common.py from patch as suggested in code review.

    Change-Id: I0fe11f66384f1aa8919bbb3f5cdf5339f0cbdfc6
    Partial-Bug:1257725

[Julie Pichon (jpichon)]

From the comments, bug 1276243 is also related.

[Openstack Gerrit (openstack-gerrit)]

Reviewed: https://review.openstack.org/85322
Committed: https://git.openstack.org/cgit/openstack/horizon/commit/?id=c4146c4016cc8d84e7c89ade0b1c1d6221d32ab6
Submitter: Jenkins
Branch: master

commit c4146c4016cc8d84e7c89ade0b1c1d6221d32ab6
Author: Akihiro Motoki <email address hidden>
Date: Fri Apr 4 20:49:14 2014 +0900

    Add tox env to build docs

    In django-based projects, we need to specify DJANGO_SETTINGS_MODULE
    when running docs build. It is required to addresses the warnings of
    docs build job in the gate.

    This commit also changes run_tests.sh --docs to use "python setup.py
    build_sphinx" to match tox docs env. This change addresses all sphinx
    build warning except keystone v3 related following warning.
    I believe it is useful.
      NoReverseMatch: u'domains' is not a registered namespace
      inside 'horizon:admin'

    Closes-Bug: #1302532
    Related-Bug: #1257725

    Change-Id: I3663b81b58be3c6cb05e4af914f768c28b21ea07

[OpenStack Infra (hudson-openstack)]

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

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/92703
Committed: https://git.openstack.org/cgit/openstack/horizon/commit/?id=628e908a3dc3d66488a2f65cc5f3a1865f7859b1
Submitter: Jenkins
Branch: master

commit 628e908a3dc3d66488a2f65cc5f3a1865f7859b1
Author: Gary W. Smith <email address hidden>
Date: Wed May 7 12:59:38 2014 -0700

    Fix build instructions and formatting in README

    - Fix manual build command
    - Fix formatting of command-line examples, directory names
    - Rename 'folder' to 'directory' for consistency
    - Update sphinx URL

    Partial-bug: #1257725
    Change-Id: I078bc5b9c931d4bf4e57c8fe7b335db99cc92c29

[OpenStack Infra (hudson-openstack)]

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

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/99812
Committed: https://git.openstack.org/cgit/openstack/horizon/commit/?id=1f38f871387e58766f3c19aadacdb804163f316c
Submitter: Jenkins
Branch: master

commit 1f38f871387e58766f3c19aadacdb804163f316c
Author: Gary W. Smith <email address hidden>
Date: Thu Jun 12 17:00:19 2014 -0700

    Fix keystone warnings while building docs

    When building the documentation via run_tests.sh, doc/source/conf.py
    explicitly sets the DJANGO_SETTINGS_MODULE environment variable,
    overriding any existing value that it already has. Furthermore, it sets
    it to point to a settings file that does not use keystone v3, which
    is expected by the tests (and is the source of the warning). Note that
    when running unit tests via run_tests.sh, a different settings file is
    supplied which DOES use keystone v3.

    Change the doc/source/conf.py to only set DJANGO_SETTINGS_MODULE if it
    is not already set. Change tox.ini and run_tests.sh to set
    DJANGO_SETTINGS_MODULE to the same settings file used by the unit tests,
    with keystone v3 support.

    Change-Id: Ib297e4188f2426cf575300998bc9d50f36e48f4f
    Closes-Bug: #1257725