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
This commit is contained in:
Ian Wienand
parent
db48db1cf0
commit
7cd16ce48a
@ -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%
|
|
||||||
@ -62,8 +62,7 @@ appear in the file will be used.
|
|||||||
A specific meta-section ``local|localrc`` is used to provide a default
|
A specific meta-section ``local|localrc`` is used to provide a default
|
||||||
``localrc`` file (actually ``.localrc.auto``). This allows all custom
|
``localrc`` file (actually ``.localrc.auto``). This allows all custom
|
||||||
settings for DevStack to be contained in a single file. If ``localrc``
|
settings for DevStack to be contained in a single file. If ``localrc``
|
||||||
exists it will be used instead to preserve backward-compatibility. More
|
exists it will be used instead to preserve backward-compatibility.
|
||||||
details on the :doc:`contents of local.conf <local.conf>` are available.
|
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
@ -84,6 +83,76 @@ Also note that the ``localrc`` section is sourced as a shell script
|
|||||||
fragment and MUST conform to the shell requirements, specifically no
|
fragment and MUST conform to the shell requirements, specifically no
|
||||||
whitespace around ``=`` (equals).
|
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:
|
||||||
|
|
||||||
Minimal Configuration
|
Minimal Configuration
|
||||||
@ -145,6 +214,37 @@ Configuration Notes
|
|||||||
.. contents::
|
.. contents::
|
||||||
:local:
|
: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
|
Installation Directory
|
||||||
----------------------
|
----------------------
|
||||||
|
|
||||||
@ -640,3 +740,40 @@ use the v3 API. It is possible to setup keystone without v2 API, by doing:
|
|||||||
::
|
::
|
||||||
|
|
||||||
ENABLE_IDENTITY_V2=False
|
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
|
||||||
|
|||||||
@ -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
|
|
||||||
@ -1,8 +1,16 @@
|
|||||||
DevStack - an OpenStack Community Production
|
DevStack
|
||||||
============================================
|
========
|
||||||
|
|
||||||
.. image:: assets/images/logo-blue.png
|
.. 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::
|
.. toctree::
|
||||||
:glob:
|
:glob:
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
@ -12,7 +20,6 @@ DevStack - an OpenStack Community Production
|
|||||||
plugins
|
plugins
|
||||||
plugin-registry
|
plugin-registry
|
||||||
faq
|
faq
|
||||||
changes
|
|
||||||
hacking
|
hacking
|
||||||
|
|
||||||
Quick Start
|
Quick Start
|
||||||
@ -147,11 +154,6 @@ Plugins
|
|||||||
|
|
||||||
:doc:`Extending DevStack with new features <plugins>`
|
:doc:`Extending DevStack with new features <plugins>`
|
||||||
|
|
||||||
Recent Changes
|
|
||||||
--------------
|
|
||||||
|
|
||||||
:doc:`An incomplete summary of recent changes <changes>`
|
|
||||||
|
|
||||||
FAQ
|
FAQ
|
||||||
---
|
---
|
||||||
|
|
||||||
@ -162,94 +164,3 @@ Contributing
|
|||||||
|
|
||||||
:doc:`Pitching in to make DevStack a better place <hacking>`
|
: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>`__
|
|
||||||
|
|||||||
@ -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.
|
|
||||||
@ -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
|
|
||||||
@ -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
|
|
||||||
@ -1,100 +0,0 @@
|
|||||||
#!/usr/bin/env bash
|
|
||||||
|
|
||||||
# **build_docs.sh** - Build the docs for DevStack
|
|
||||||
#
|
|
||||||
# - Install shocco if not found on ``PATH`` and ``INSTALL_SHOCCO`` is set
|
|
||||||
# - Clone ``MASTER_REPO`` branch ``MASTER_BRANCH``
|
|
||||||
# - Re-creates ``doc/build/html`` directory from existing repo + new generated script docs
|
|
||||||
|
|
||||||
# Usage:
|
|
||||||
## build_docs.sh [-o <out-dir>]
|
|
||||||
## -o <out-dir> Write the static HTML output to <out-dir>
|
|
||||||
## (Note that <out-dir> will be deleted and re-created to ensure it is clean)
|
|
||||||
|
|
||||||
# Defaults
|
|
||||||
# --------
|
|
||||||
|
|
||||||
HTML_BUILD=doc/build/html
|
|
||||||
|
|
||||||
# Keep track of the DevStack directory
|
|
||||||
TOP_DIR=$(cd $(dirname "$0")/.. && pwd)
|
|
||||||
|
|
||||||
# Uses this shocco branch: https://github.com/dtroyer/shocco/tree/rst_support
|
|
||||||
SHOCCO=${SHOCCO:-shocco}
|
|
||||||
if ! which shocco; then
|
|
||||||
if [[ ! -x $TOP_DIR/shocco/shocco ]]; then
|
|
||||||
if [[ -z "$INSTALL_SHOCCO" ]]; then
|
|
||||||
echo "shocco not found in \$PATH, please set environment variable SHOCCO"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
echo "Installing local copy of shocco"
|
|
||||||
if ! which pygmentize; then
|
|
||||||
sudo pip install Pygments
|
|
||||||
fi
|
|
||||||
if ! which rst2html.py; then
|
|
||||||
sudo pip install docutils
|
|
||||||
fi
|
|
||||||
git clone -b rst_support https://github.com/dtroyer/shocco shocco
|
|
||||||
cd shocco
|
|
||||||
./configure
|
|
||||||
make || exit
|
|
||||||
cd ..
|
|
||||||
fi
|
|
||||||
SHOCCO=$TOP_DIR/shocco/shocco
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Process command-line args
|
|
||||||
while getopts o: c; do
|
|
||||||
case $c in
|
|
||||||
o) HTML_BUILD=$OPTARG
|
|
||||||
;;
|
|
||||||
esac
|
|
||||||
done
|
|
||||||
shift `expr $OPTIND - 1`
|
|
||||||
|
|
||||||
|
|
||||||
# Processing
|
|
||||||
# ----------
|
|
||||||
|
|
||||||
# Ensure build dir exists
|
|
||||||
mkdir -p $HTML_BUILD
|
|
||||||
|
|
||||||
# Get fully qualified dirs
|
|
||||||
FQ_HTML_BUILD=$(cd $HTML_BUILD && pwd)
|
|
||||||
|
|
||||||
# Insert automated bits
|
|
||||||
GLOG=$(mktemp gitlogXXXX)
|
|
||||||
echo "<ul>" >$GLOG
|
|
||||||
git log \
|
|
||||||
--pretty=format:' <li>%s - <em>Commit <a href="https://review.openstack.org/#q,%h,n,z">%h</a> %cd</em></li>' \
|
|
||||||
--date=short \
|
|
||||||
--since '6 months ago' | grep -v Merge >>$GLOG
|
|
||||||
echo "</ul>" >>$GLOG
|
|
||||||
sed -i~ -e $"/^.*%GIT_LOG%.*$/r $GLOG" -e $"/^.*%GIT_LOG%.*$/s/^.*%GIT_LOG%.*$//" $FQ_HTML_BUILD/changes.html
|
|
||||||
rm -f $GLOG
|
|
||||||
|
|
||||||
# Build list of scripts to process
|
|
||||||
FILES=""
|
|
||||||
for f in $(find . \( -name .git -o -name .tox \) -prune -o \( -type f -name \*.sh -not -path \*shocco/\* -print \)); do
|
|
||||||
echo $f
|
|
||||||
FILES+="$f "
|
|
||||||
mkdir -p $FQ_HTML_BUILD/`dirname $f`;
|
|
||||||
$SHOCCO $f > $FQ_HTML_BUILD/$f.html
|
|
||||||
done
|
|
||||||
for f in $(find functions functions-common inc lib pkg samples -type f -name \* ! -name *.md ! -name *.conf); do
|
|
||||||
echo $f
|
|
||||||
FILES+="$f "
|
|
||||||
mkdir -p $FQ_HTML_BUILD/`dirname $f`;
|
|
||||||
$SHOCCO $f > $FQ_HTML_BUILD/$f.html
|
|
||||||
done
|
|
||||||
echo "$FILES" >doc/files
|
|
||||||
|
|
||||||
# Clean up or report the temp workspace
|
|
||||||
if [[ -n REPO && -n $PUSH_REPO ]]; then
|
|
||||||
echo rm -rf $TMP_ROOT
|
|
||||||
else
|
|
||||||
if [[ -z "$TMP_ROOT" ]]; then
|
|
||||||
TMP_ROOT="$(pwd)"
|
|
||||||
fi
|
|
||||||
echo "Built docs in $HTML_BUILD"
|
|
||||||
fi
|
|
||||||
7
tox.ini
7
tox.ini
@ -17,7 +17,6 @@ whitelist_externals = bash
|
|||||||
commands = bash -c "find {toxinidir} \
|
commands = bash -c "find {toxinidir} \
|
||||||
-not \( -type d -name .?\* -prune \) \
|
-not \( -type d -name .?\* -prune \) \
|
||||||
-not \( -type d -name doc -prune \) \
|
-not \( -type d -name doc -prune \) \
|
||||||
-not \( -type d -name shocco -prune \) \
|
|
||||||
-not \( -type f -name localrc -prune \) \
|
-not \( -type f -name localrc -prune \) \
|
||||||
-type f \
|
-type f \
|
||||||
-not -name \*~ \
|
-not -name \*~ \
|
||||||
@ -48,7 +47,5 @@ deps =
|
|||||||
whitelist_externals = bash
|
whitelist_externals = bash
|
||||||
setenv =
|
setenv =
|
||||||
TOP_DIR={toxinidir}
|
TOP_DIR={toxinidir}
|
||||||
INSTALL_SHOCCO=true
|
commands =
|
||||||
commands =
|
python setup.py build_sphinx
|
||||||
python setup.py build_sphinx
|
|
||||||
bash tools/build_docs.sh
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user