Remove shocco docs and other cleanups
This is a fairly opinionated change to do some spring cleaning on the
documentation.
The current output of shocco as rendered at [1] is completely broken.
I can not see that it is worth us maintaining this. Honestly, the
github page does a better job at showing the scripts with a bit of
formatting. The "changes" page is similarly useless today. cgit or
github show allow browsing of changes in the repo better. Both are
removed along with support scripts.
When you currently hit the first page, it gives no clue as to what
DevStack actually is. Add a paragraph explaining that, and link to
the cgit for easy source browsing.
stackrc.rst is not necessary; the stuff about database backends is
already discussed in configuration.rst; move the things about service
repos into a section of configuration.rst.
The discussion in openrc.rst is moved into the configuration.rst file.
localrc.conf.rst was just a paragraph pointing back to
configuration.rst; this is removed.
The variables described in exercise.rst are moved into a separate
section of configuration.rst
[1] http://docs.openstack.org/developer/devstack/#scripts
Change-Id: Ie7f4b265368f1d10a8908d75e11d625b2cc39e7c
diff --git a/doc/source/changes.rst b/doc/source/changes.rst
deleted file mode 100644
index 19fce0f..0000000
--- a/doc/source/changes.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-=======
-Changes
-=======
-
-Recent Changes What's been happening?
-=====================================
-
-These are the commits to DevStack for the last six months. For the
-complete list see `the DevStack project in
-Gerrit <https://review.openstack.org/#/q/status:merged+project:openstack-dev/devstack,n,z>`__.
-
-%GIT_LOG%
diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst
index f3e4896..3c77f4d 100644
--- a/doc/source/configuration.rst
+++ b/doc/source/configuration.rst
@@ -62,8 +62,7 @@
A specific meta-section ``local|localrc`` is used to provide a default
``localrc`` file (actually ``.localrc.auto``). This allows all custom
settings for DevStack to be contained in a single file. If ``localrc``
-exists it will be used instead to preserve backward-compatibility. More
-details on the :doc:`contents of local.conf <local.conf>` are available.
+exists it will be used instead to preserve backward-compatibility.
::
@@ -84,6 +83,76 @@
fragment and MUST conform to the shell requirements, specifically no
whitespace around ``=`` (equals).
+openrc
+======
+
+``openrc`` configures login credentials suitable for use with the
+OpenStack command-line tools. ``openrc`` sources ``stackrc`` at the
+beginning (which in turn sources the ``localrc`` section of
+``local.conf``) in order to pick up ``HOST_IP`` and/or ``SERVICE_HOST``
+to use in the endpoints. The values shown below are the default values.
+
+OS\_PROJECT\_NAME (OS\_TENANT\_NAME)
+ Keystone has
+ standardized the term *project* as the entity that owns resources. In
+ some places references still exist to the previous term
+ *tenant* for this use. Also, *project\_name* is preferred to
+ *project\_id*. OS\_TENANT\_NAME remains supported for compatibility
+ with older tools.
+
+ ::
+
+ OS_PROJECT_NAME=demo
+
+OS\_USERNAME
+ In addition to the owning entity (project), OpenStack calls the entity
+ performing the action *user*.
+
+ ::
+
+ OS_USERNAME=demo
+
+OS\_PASSWORD
+ Keystone's default authentication requires a password be provided.
+ The usual cautions about putting passwords in environment variables
+ apply, for most DevStack uses this may be an acceptable tradeoff.
+
+ ::
+
+ OS_PASSWORD=secret
+
+HOST\_IP, SERVICE\_HOST
+ Set API endpoint host using ``HOST_IP``. ``SERVICE_HOST`` may also
+ be used to specify the endpoint, which is convenient for some
+ ``local.conf`` configurations. Typically, ``HOST_IP`` is set in the
+ ``localrc`` section.
+
+ ::
+
+ HOST_IP=127.0.0.1
+ SERVICE_HOST=$HOST_IP
+
+OS\_AUTH\_URL
+ Authenticating against an OpenStack cloud using Keystone returns a
+ *Token* and *Service Catalog*. The catalog contains the endpoints
+ for all services the user/tenant has access to - including Nova,
+ Glance, Keystone and Swift.
+
+ ::
+
+ OS_AUTH_URL=http://$SERVICE_HOST:5000/v2.0
+
+KEYSTONECLIENT\_DEBUG, NOVACLIENT\_DEBUG
+ Set command-line client log level to ``DEBUG``. These are commented
+ out by default.
+
+ ::
+
+ # export KEYSTONECLIENT_DEBUG=1
+ # export NOVACLIENT_DEBUG=1
+
+
+
.. _minimal-configuration:
Minimal Configuration
@@ -145,6 +214,37 @@
.. contents::
:local:
+Service Repos
+-------------
+
+The Git repositories used to check out the source for each service are
+controlled by a pair of variables set for each service. ``*_REPO``
+points to the repository and ``*_BRANCH`` selects which branch to
+check out. These may be overridden in ``local.conf`` to pull source
+from a different repo for testing, such as a Gerrit branch
+proposal. ``GIT_BASE`` points to the primary repository server.
+
+ ::
+
+ NOVA_REPO=$GIT_BASE/openstack/nova.git
+ NOVA_BRANCH=master
+
+To pull a branch directly from Gerrit, get the repo and branch from
+the Gerrit review page:
+
+ ::
+
+ git fetch https://review.openstack.org/p/openstack/nova refs/changes/50/5050/1 && git checkout FETCH_HEAD
+
+ The repo is the stanza following ``fetch`` and the branch is the
+ stanza following that:
+
+ ::
+
+ NOVA_REPO=https://review.openstack.org/p/openstack/nova
+ NOVA_BRANCH=refs/changes/50/5050/1
+
+
Installation Directory
----------------------
@@ -640,3 +740,40 @@
::
ENABLE_IDENTITY_V2=False
+
+Exercises
+~~~~~~~~~
+
+``exerciserc`` is used to configure settings for the exercise scripts.
+The values shown below are the default values. These can all be
+overridden by setting them in the ``localrc`` section.
+
+* Max time to wait while vm goes from build to active state
+
+ ::
+
+ ACTIVE_TIMEOUT==30
+
+* Max time to wait for proper IP association and dis-association.
+
+ ::
+
+ ASSOCIATE_TIMEOUT=15
+
+* Max time till the vm is bootable
+
+ ::
+
+ BOOT_TIMEOUT=30
+
+* Max time from run instance command until it is running
+
+ ::
+
+ RUNNING_TIMEOUT=$(($BOOT_TIMEOUT + $ACTIVE_TIMEOUT))
+
+* Max time to wait for a vm to terminate
+
+ ::
+
+ TERMINATE_TIMEOUT=30
diff --git a/doc/source/exerciserc.rst b/doc/source/exerciserc.rst
deleted file mode 100644
index dacae2e..0000000
--- a/doc/source/exerciserc.rst
+++ /dev/null
@@ -1,42 +0,0 @@
-==============================
-exerciserc - Exercise Settings
-==============================
-
-``exerciserc`` is used to configure settings for the exercise scripts.
-The values shown below are the default values. These can all be
-overridden by setting them in the ``localrc`` section.
-
-ACTIVE\_TIMEOUT
- Max time to wait while vm goes from build to active state
-
- ::
-
- ACTIVE_TIMEOUT==30
-
-ASSOCIATE\_TIMEOUT
- Max time to wait for proper IP association and dis-association.
-
- ::
-
- ASSOCIATE_TIMEOUT=15
-
-BOOT\_TIMEOUT
- Max time till the vm is bootable
-
- ::
-
- BOOT_TIMEOUT=30
-
-RUNNING\_TIMEOUT
- Max time from run instance command until it is running
-
- ::
-
- RUNNING_TIMEOUT=$(($BOOT_TIMEOUT + $ACTIVE_TIMEOUT))
-
-TERMINATE\_TIMEOUT
- Max time to wait for a vm to terminate
-
- ::
-
- TERMINATE_TIMEOUT=30
diff --git a/doc/source/index.rst b/doc/source/index.rst
index c79b2ce..c4a7c59 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,8 +1,16 @@
-DevStack - an OpenStack Community Production
-============================================
+DevStack
+========
.. image:: assets/images/logo-blue.png
+DevStack is a series of extensible scripts used to quickly bring up a
+complete OpenStack environment. It is used interactively as a
+development environment and as the basis for much of the OpenStack
+project's functional testing.
+
+The source is available at
+`<https://git.openstack.org/cgit/openstack-dev/devstack>`__.
+
.. toctree::
:glob:
:maxdepth: 1
@@ -12,7 +20,6 @@
plugins
plugin-registry
faq
- changes
hacking
Quick Start
@@ -147,11 +154,6 @@
:doc:`Extending DevStack with new features <plugins>`
-Recent Changes
---------------
-
-:doc:`An incomplete summary of recent changes <changes>`
-
FAQ
---
@@ -162,94 +164,3 @@
:doc:`Pitching in to make DevStack a better place <hacking>`
-Code
-====
-
-*A look at the bits that make it all go*
-
-Scripts
--------
-
-* `stack.sh <stack.sh.html>`__ - The main script
-* `functions <functions.html>`__ - DevStack-specific functions
-* `functions-common <functions-common.html>`__ - Functions shared with other projects
-* `lib/apache <lib/apache.html>`__
-* `lib/ceph <lib/ceph.html>`__
-* `lib/cinder <lib/cinder.html>`__
-* `lib/database <lib/database.html>`__
-* `lib/dstat <lib/dstat.html>`__
-* `lib/glance <lib/glance.html>`__
-* `lib/heat <lib/heat.html>`__
-* `lib/horizon <lib/horizon.html>`__
-* `lib/infra <lib/infra.html>`__
-* `lib/keystone <lib/keystone.html>`__
-* `lib/ldap <lib/ldap.html>`__
-* `lib/neutron-legacy <lib/neutron-legacy.html>`__
-* `lib/nova <lib/nova.html>`__
-* `lib/oslo <lib/oslo.html>`__
-* `lib/rpc\_backend <lib/rpc_backend.html>`__
-* `lib/swift <lib/swift.html>`__
-* `lib/tempest <lib/tempest.html>`__
-* `lib/tls <lib/tls.html>`__
-* `lib/trove <lib/trove.html>`__
-* `unstack.sh <unstack.sh.html>`__
-* `clean.sh <clean.sh.html>`__
-* `run\_tests.sh <run_tests.sh.html>`__
-
-* `extras.d/60-ceph.sh <extras.d/60-ceph.sh.html>`__
-* `extras.d/70-tuskar.sh <extras.d/70-tuskar.sh.html>`__
-* `extras.d/80-tempest.sh <extras.d/80-tempest.sh.html>`__
-
-* `inc/ini-config <inc/ini-config.html>`__
-* `inc/meta-config <inc/meta-config.html>`__
-* `inc/python <inc/python.html>`__
-
-* `pkg/elasticsearch.sh <pkg/elasticsearch.sh.html>`_
-
-Configuration
--------------
-
-.. toctree::
- :glob:
- :maxdepth: 1
-
- local.conf
- stackrc
- openrc
- exerciserc
-
-Tools
------
-
-* `tools/build\_docs.sh <tools/build_docs.sh.html>`__
-* `tools/build\_venv.sh <tools/build_venv.sh.html>`__
-* `tools/create-stack-user.sh <tools/create-stack-user.sh.html>`__
-* `tools/create\_userrc.sh <tools/create_userrc.sh.html>`__
-* `tools/fixup\_stuff.sh <tools/fixup_stuff.sh.html>`__
-* `tools/info.sh <tools/info.sh.html>`__
-* `tools/install\_pip.sh <tools/install_pip.sh.html>`__
-* `tools/install\_prereqs.sh <tools/install_prereqs.sh.html>`__
-* `tools/make\_cert.sh <tools/make_cert.sh.html>`__
-* `tools/upload\_image.sh <tools/upload_image.sh.html>`__
-
-Samples
--------
-
-* `local.sh <samples/local.sh.html>`__
-
-Exercises
----------
-
-* `exercise.sh <exercise.sh.html>`__
-* `exercises/aggregates.sh <exercises/aggregates.sh.html>`__
-* `exercises/boot\_from\_volume.sh <exercises/boot_from_volume.sh.html>`__
-* `exercises/bundle.sh <exercises/bundle.sh.html>`__
-* `exercises/client-args.sh <exercises/client-args.sh.html>`__
-* `exercises/client-env.sh <exercises/client-env.sh.html>`__
-* `exercises/euca.sh <exercises/euca.sh.html>`__
-* `exercises/floating\_ips.sh <exercises/floating_ips.sh.html>`__
-* `exercises/horizon.sh <exercises/horizon.sh.html>`__
-* `exercises/neutron-adv-test.sh <exercises/neutron-adv-test.sh.html>`__
-* `exercises/sec\_groups.sh <exercises/sec_groups.sh.html>`__
-* `exercises/swift.sh <exercises/swift.sh.html>`__
-* `exercises/volumes.sh <exercises/volumes.sh.html>`__
diff --git a/doc/source/local.conf.rst b/doc/source/local.conf.rst
deleted file mode 100644
index a1ca60a..0000000
--- a/doc/source/local.conf.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-==========================
-local.conf - User Settings
-==========================
-
-``local.conf`` is a user-maintained settings file that is sourced in
-``stackrc``. It contains a section that replaces the historical
-``localrc`` file. See the description of
-:doc:`local.conf <configuration>` for more details about the mechanics
-of the file.
diff --git a/doc/source/openrc.rst b/doc/source/openrc.rst
deleted file mode 100644
index d28b568..0000000
--- a/doc/source/openrc.rst
+++ /dev/null
@@ -1,68 +0,0 @@
-=====================================
-openrc - User Authentication Settings
-=====================================
-
-``openrc`` configures login credentials suitable for use with the
-OpenStack command-line tools. ``openrc`` sources ``stackrc`` at the
-beginning (which in turn sources the ``localrc`` section of
-``local.conf``) in order to pick up ``HOST_IP`` and/or ``SERVICE_HOST``
-to use in the endpoints. The values shown below are the default values.
-
-OS\_PROJECT\_NAME (OS\_TENANT\_NAME)
- Keystone has
- standardized the term *project* as the entity that owns resources. In
- some places references still exist to the previous term
- *tenant* for this use. Also, *project\_name* is preferred to
- *project\_id*. OS\_TENANT\_NAME remains supported for compatibility
- with older tools.
-
- ::
-
- OS_PROJECT_NAME=demo
-
-OS\_USERNAME
- In addition to the owning entity (project), OpenStack calls the entity
- performing the action *user*.
-
- ::
-
- OS_USERNAME=demo
-
-OS\_PASSWORD
- Keystone's default authentication requires a password be provided.
- The usual cautions about putting passwords in environment variables
- apply, for most DevStack uses this may be an acceptable tradeoff.
-
- ::
-
- OS_PASSWORD=secret
-
-HOST\_IP, SERVICE\_HOST
- Set API endpoint host using ``HOST_IP``. ``SERVICE_HOST`` may also
- be used to specify the endpoint, which is convenient for some
- ``local.conf`` configurations. Typically, ``HOST_IP`` is set in the
- ``localrc`` section.
-
- ::
-
- HOST_IP=127.0.0.1
- SERVICE_HOST=$HOST_IP
-
-OS\_AUTH\_URL
- Authenticating against an OpenStack cloud using Keystone returns a
- *Token* and *Service Catalog*. The catalog contains the endpoints
- for all services the user/project has access to - including Nova,
- Glance, Keystone and Swift.
-
- ::
-
- OS_AUTH_URL=http://$SERVICE_HOST:5000/v2.0
-
-KEYSTONECLIENT\_DEBUG, NOVACLIENT\_DEBUG
- Set command-line client log level to ``DEBUG``. These are commented
- out by default.
-
- ::
-
- # export KEYSTONECLIENT_DEBUG=1
- # export NOVACLIENT_DEBUG=1
diff --git a/doc/source/stackrc.rst b/doc/source/stackrc.rst
deleted file mode 100644
index 81d4b80..0000000
--- a/doc/source/stackrc.rst
+++ /dev/null
@@ -1,66 +0,0 @@
-===========================
-stackrc - DevStack Settings
-===========================
-
-``stackrc`` is the primary configuration file for DevStack. It contains
-all of the settings that control the services started and the
-repositories used to download the source for those services. ``stackrc``
-sources the ``localrc`` section of ``local.conf`` to perform the default
-overrides.
-
-DATABASE\_TYPE
- Select the database backend to use. The default is ``mysql``,
- ``postgresql`` is also available.
-ENABLED\_SERVICES
- Specify which services to launch. These generally correspond to
- screen tabs. The default includes: Glance (API and Registry),
- Keystone, Nova (API, Certificate, Object Store, Compute, Network,
- Scheduler, Certificate Authentication), Cinder
- (Scheduler, API, Volume), Horizon, MySQL, RabbitMQ, Tempest.
-
- ::
-
- ENABLED_SERVICES=g-api,g-reg,key,n-api,n-crt,n-cpu,n-net,n-cond,c-sch,c-api,c-vol,n-sch,n-cauth,horizon,rabbit,tempest,$DATABASE_TYPE
-
- Other services that are not enabled by default can be enabled in
- ``localrc``. For example, to add Swift, use the following service
- names:
-
- ::
-
- enable_service s-proxy s-object s-container s-account
-
- A service can similarly be disabled:
-
- ::
-
- disable_service horizon
-
-Service Repos
- The Git repositories used to check out the source for each service
- are controlled by a pair of variables set for each service.
- ``*_REPO`` points to the repository and ``*_BRANCH`` selects which
- branch to check out. These may be overridden in ``local.conf`` to
- pull source from a different repo for testing, such as a Gerrit
- branch proposal. ``GIT_BASE`` points to the primary repository
- server.
-
- ::
-
- NOVA_REPO=$GIT_BASE/openstack/nova.git
- NOVA_BRANCH=master
-
- To pull a branch directly from Gerrit, get the repo and branch from
- the Gerrit review page:
-
- ::
-
- git fetch https://review.openstack.org/p/openstack/nova refs/changes/50/5050/1 && git checkout FETCH_HEAD
-
- The repo is the stanza following ``fetch`` and the branch is the
- stanza following that:
-
- ::
-
- NOVA_REPO=https://review.openstack.org/p/openstack/nova
- NOVA_BRANCH=refs/changes/50/5050/1