From ea3cdfad1fe6f63c8a6acdd4df4b5c4db85fabb5 Mon Sep 17 00:00:00 2001 From: Dean Troyer Date: Sat, 8 Nov 2014 08:29:16 -0600 Subject: [PATCH] Pass through the rest of the docs Do the link cleanups and update a handful of things that were out of date. Change-Id: I758027bf3577c66cfb13df963516823a5c247080 --- doc/source/configuration.rst | 2 +- doc/source/contributing.rst | 17 ++++++------- doc/source/faq.rst | 7 ++---- doc/source/guides/multinode-lab.rst | 6 ++--- doc/source/guides/single-machine.rst | 4 ++-- doc/source/local.conf.rst | 4 ++-- doc/source/openrc.rst | 36 +++++++++++----------------- doc/source/overview.rst | 2 +- doc/source/plugins.rst | 4 ++-- doc/source/stackrc.rst | 4 ++-- 10 files changed, 38 insertions(+), 48 deletions(-) diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index eba295622b..a4d940d762 100644 --- a/doc/source/configuration.rst +++ b/doc/source/configuration.rst @@ -74,7 +74,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 `contents of localrc `__ are available. +details on the :doc:`contents of local.conf ` are available. :: diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index b4f9f37902..7ca3d64afd 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -59,16 +59,17 @@ Code The DevStack repo generally keeps all of the primary scripts at the root level. -``docs`` - Contains the source for this website. It is built using -``tools/build_docs.sh``. +``doc`` - Contains the Sphinx source for the documentation. +``tools/build_docs.sh`` is used to generate the HTML versions of the +DevStack scripts. A complete doc build can be run with ``tox -edocs``. -``exercises`` - Contains the test scripts used to validate and +``exercises`` - Contains the test scripts used to sanity-check and demonstrate some OpenStack functions. These scripts know how to exit early or skip services that are not enabled. ``extras.d`` - Contains the dispatch scripts called by the hooks in -``stack.sh``, ``unstack.sh`` and ``clean.sh``. See `the plugins -docs `__ for more information. +``stack.sh``, ``unstack.sh`` and ``clean.sh``. See :doc:`the plugins +docs ` for more information. ``files`` - Contains a variety of otherwise lost files used in configuring and operating DevStack. This includes templates for @@ -84,10 +85,10 @@ there are some for system services and project plugins. DevStack repo. ``tests`` - the DevStack test suite is rather sparse, mostly consisting -of test of specific fragile functions in the ``functions`` file. +of test of specific fragile functions in the ``functions`` and +``functions-common`` files. -``tools`` - Contains a collection of stand-alone scripts, some of which -have aged a bit (does anyone still do ramdisk installs?). While these +``tools`` - Contains a collection of stand-alone scripts. While these may reference the top-level DevStack configuration they can generally be run alone. There are also some sub-directories to support specific environments such as XenServer. diff --git a/doc/source/faq.rst b/doc/source/faq.rst index 7b33b41741..b7943ba130 100644 --- a/doc/source/faq.rst +++ b/doc/source/faq.rst @@ -47,11 +47,8 @@ Q: I'd like to help! and bug reports go to `LaunchPad `__. Contributions follow the usual process as described in the `OpenStack - wiki `__ even though - DevStack is not an official OpenStack project. This site is housed - in the CloudBuilder's - `github `__ in the - gh-pages branch. + wiki `__. This Sphinx + documentation is housed in the doc directory. Q: Why not use packages? A: Unlike packages, DevStack leaves your cloud ready to develop - checkouts of the code and services running in screen. However, many diff --git a/doc/source/guides/multinode-lab.rst b/doc/source/guides/multinode-lab.rst index 1c53227835..4c60b6a745 100644 --- a/doc/source/guides/multinode-lab.rst +++ b/doc/source/guides/multinode-lab.rst @@ -16,9 +16,9 @@ download the `Minimal CD `__ for Ubuntu releases since DevStack will download & install all the additional dependencies. The netinstall ISO is available for -`Fedora `__ +`Fedora `__ and -`CentOS/RHEL `__. +`CentOS/RHEL `__. Install a couple of packages to bootstrap configuration: @@ -284,7 +284,7 @@ Volumes DevStack will automatically use an existing LVM volume group named ``stack-volumes`` to store cloud-created volumes. If ``stack-volumes`` -doesn't exist, DevStack will set up a 5Gb loop-mounted file to contain +doesn't exist, DevStack will set up a 10Gb loop-mounted file to contain it. This obviously limits the number and size of volumes that can be created inside OpenStack. The size can be overridden by setting ``VOLUME_BACKING_FILE_SIZE`` in ``local.conf``. diff --git a/doc/source/guides/single-machine.rst b/doc/source/guides/single-machine.rst index 9eaa38a49a..a7a1099bc7 100644 --- a/doc/source/guides/single-machine.rst +++ b/doc/source/guides/single-machine.rst @@ -17,9 +17,9 @@ download the `Minimal CD `__ for Ubuntu releases since DevStack will download & install all the additional dependencies. The netinstall ISO is available for -`Fedora `__ +`Fedora `__ and -`CentOS/RHEL `__. +`CentOS/RHEL `__. You may be tempted to use a desktop distro on a laptop, it will probably work but you may need to tell Network Manager to keep its fingers off the interface(s) that OpenStack uses for bridging. diff --git a/doc/source/local.conf.rst b/doc/source/local.conf.rst index a9dfcb0ac7..b2f7557e6d 100644 --- a/doc/source/local.conf.rst +++ b/doc/source/local.conf.rst @@ -4,6 +4,6 @@ local.conf - User Settings ``local.conf`` is a user-maintained setings file that is sourced in ``stackrc``. It contains a section that replaces the historical -``localrc`` file. See `the description of -local.conf `__ for more details about the mechanics +``localrc`` file. See the description of +:doc:`local.conf ` for more details about the mechanics of the file. diff --git a/doc/source/openrc.rst b/doc/source/openrc.rst index dc12f76b84..56ff5c2edb 100644 --- a/doc/source/openrc.rst +++ b/doc/source/openrc.rst @@ -8,29 +8,30 @@ beginning (which in turn sources the ``localrc`` setion 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\_TENANT\_NAME - The introduction of Keystone to the OpenStack ecosystem has - standardized the term *tenant* as the entity that owns resources. In - some places references still exist to the original Nova term - *project* for this use. Also, *tenant\_name* is preferred to - *tenant\_id*. +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_TENANT_NAME=demo + OS_PROJECT_NAME=demo OS\_USERNAME - In addition to the owning entity (tenant), Nova stores the entity - performing the action as the *user*. + In addition to the owning entity (project), OpenStack calls the entity + performing the action *user*. :: OS_USERNAME=demo OS\_PASSWORD - With Keystone you pass the keystone password instead of an api key. - Recent versions of novaclient use OS\_PASSWORD instead of - NOVA\_API\_KEYs or NOVA\_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. :: @@ -39,7 +40,7 @@ OS\_PASSWORD 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 - ``localrc`` configurations. Typically, ``HOST_IP`` is set in the + ``local.conf`` configurations. Typically, ``HOST_IP`` is set in the ``localrc`` section. :: @@ -57,15 +58,6 @@ OS\_AUTH\_URL OS_AUTH_URL=http://$SERVICE_HOST:5000/v2.0 -GLANCE\_HOST - Some exercises call Glance directly. On a single-node installation, - Glance should be listening on ``HOST_IP``. If its running elsewhere - it can be set here. - - :: - - GLANCE_HOST=$HOST_IP - KEYSTONECLIENT\_DEBUG, NOVACLIENT\_DEBUG Set command-line client log level to ``DEBUG``. These are commented out by default. diff --git a/doc/source/overview.rst b/doc/source/overview.rst index e3cf75dd29..40782403fa 100644 --- a/doc/source/overview.rst +++ b/doc/source/overview.rst @@ -73,7 +73,7 @@ Compute (Nova), Network (Nova), Dashboard (Horizon), Orchestration (Heat) Additional services not included directly in DevStack can be tied in to -``stack.sh`` using the `plugin mechanism `__ to call +``stack.sh`` using the :doc:`plugin mechanism ` to call scripts that perform the configuration and startup of the service. Node Configurations diff --git a/doc/source/plugins.rst b/doc/source/plugins.rst index 282c1a4a3b..b4136c4653 100644 --- a/doc/source/plugins.rst +++ b/doc/source/plugins.rst @@ -8,8 +8,8 @@ support for additional projects and features. Extras.d Hooks ~~~~~~~~~~~~~~ -These relatively new hooks are an extension of the existing calls from -``stack.sh`` at the end of its run, plus ``unstack.sh`` and +These hooks are an extension of the service calls in +``stack.sh`` at specific points in its run, plus ``unstack.sh`` and ``clean.sh``. A number of the higher-layer projects are implemented in DevStack using this mechanism. diff --git a/doc/source/stackrc.rst b/doc/source/stackrc.rst index 0faab45c2f..b21f74f761 100644 --- a/doc/source/stackrc.rst +++ b/doc/source/stackrc.rst @@ -15,12 +15,12 @@ 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, VNC proxies, Certificate Authentication), Cinder + Scheduler, Certificate Authentication), Cinder (Scheduler, API, Volume), Horizon, MySQL, RabbitMQ, Tempest. :: - ENABLED_SERVICES=g-api,g-reg,key,n-api,n-crt,n-obj,n-cpu,n-net,n-cond,cinder,c-sch,c-api,c-vol,n-sch,n-novnc,n-xvnc,n-cauth,horizon,rabbit,tempest,$DATABASE_TYPE + ENABLED_SERVICES=g-api,g-reg,key,n-api,n-crt,n-obj,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