From 1ae04e7d41a1f5d65708b89787f45ec0bbb32d9c Mon Sep 17 00:00:00 2001 From: Chris Dent Date: Tue, 11 Dec 2018 12:42:50 +0000 Subject: [PATCH] Tune up documentation to be more useful The cookiecutter template includes more documentation than we need, so remove lots of extraneous stuff and lay in the basics. Change-Id: I6ed22f70153b00844e8de05d186ecc780debc48c --- CONTRIBUTING.rst | 7 +- README.rst | 22 ++++-- doc/source/admin/index.rst | 5 -- doc/source/cli/index.rst | 5 -- doc/source/configuration/index.rst | 5 -- doc/source/contributor/contributing.rst | 4 -- doc/source/contributor/index.rst | 13 ++-- doc/source/index.rst | 23 ++----- doc/source/install/common_configure.rst | 10 --- doc/source/install/common_prerequisites.rst | 75 --------------------- doc/source/install/get_started.rst | 9 --- doc/source/install/index.rst | 22 +++--- doc/source/install/install-obs.rst | 34 ---------- doc/source/install/install-rdo.rst | 33 --------- doc/source/install/install-ubuntu.rst | 31 --------- doc/source/install/install.rst | 20 ------ doc/source/install/next-steps.rst | 9 --- doc/source/install/verify.rst | 24 ------- doc/source/library/index.rst | 7 -- doc/source/readme.rst | 1 - doc/source/reference/index.rst | 5 -- doc/source/user/index.rst | 15 +++-- 22 files changed, 51 insertions(+), 328 deletions(-) delete mode 100644 doc/source/admin/index.rst delete mode 100644 doc/source/cli/index.rst delete mode 100644 doc/source/configuration/index.rst delete mode 100644 doc/source/contributor/contributing.rst delete mode 100644 doc/source/install/common_configure.rst delete mode 100644 doc/source/install/common_prerequisites.rst delete mode 100644 doc/source/install/get_started.rst delete mode 100644 doc/source/install/install-obs.rst delete mode 100644 doc/source/install/install-rdo.rst delete mode 100644 doc/source/install/install-ubuntu.rst delete mode 100644 doc/source/install/install.rst delete mode 100644 doc/source/install/next-steps.rst delete mode 100644 doc/source/install/verify.rst delete mode 100644 doc/source/library/index.rst delete mode 100644 doc/source/readme.rst delete mode 100644 doc/source/reference/index.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index f97e417..038347e 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,15 +1,18 @@ If you would like to contribute to the development of OpenStack, you must follow the steps in this page: - http://docs.openstack.org/infra/manual/developers.html +http://docs.openstack.org/infra/manual/developers.html If you already have a good understanding of how the system works and your OpenStack accounts are set up, you can skip to the development workflow section of this documentation to learn how changes to OpenStack should be submitted for review via the Gerrit tool: - http://docs.openstack.org/infra/manual/developers.html#development-workflow +http://docs.openstack.org/infra/manual/developers.html#development-workflow Pull requests submitted through GitHub will be ignored. Bugs should be filed on Launchpad: https://bugs.launchpad.net/nova + +Developers of os-resource-classes can be found in the ``#openstack-placement`` +IRC channel on the ``chat.freenode.net``. diff --git a/README.rst b/README.rst index 108de29..274351c 100644 --- a/README.rst +++ b/README.rst @@ -2,17 +2,25 @@ os-resource-classes =============================== -**WIP** - -Resource Classes for OpenStack - A list of standardized resource classes for OpenStack. +A resource class is a distinct type of inventory that exists in +a cloud environment, for example ``VCPU``, ``DISK_GB``. They are +upper case with underscores. They often include a unit in their +name. + +This package provides a collection of symbols representing those +standard resource classes which are expected to be available in +any OpenStack deployment. + +There also exists a concept of custom resource classes. These +are countable types that are custom to a particular environment. +The OpenStack `placement API`_ provides a way to create these. A +custom resource class always begins with a ``CUSTOM_`` prefix. + * Free software: Apache license * Documentation: https://docs.openstack.org/os-resource-classes/latest * Source: https://git.openstack.org/cgit/openstack/os-resource-classes * Bugs: https://bugs.launchpad.net/nova --------- - -* TODO +.. _placement API: https://developer.openstack.org/api-ref/placement/ diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst deleted file mode 100644 index a091511..0000000 --- a/doc/source/admin/index.rst +++ /dev/null @@ -1,5 +0,0 @@ -==================== -Administrators guide -==================== - -Administrators guide of os-resource-classes. diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst deleted file mode 100644 index d6f0b5f..0000000 --- a/doc/source/cli/index.rst +++ /dev/null @@ -1,5 +0,0 @@ -================================ -Command line interface reference -================================ - -CLI reference of os-resource-classes. diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst deleted file mode 100644 index 5458a80..0000000 --- a/doc/source/configuration/index.rst +++ /dev/null @@ -1,5 +0,0 @@ -============= -Configuration -============= - -Configuration of os-resource-classes. diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst deleted file mode 100644 index 2aa0707..0000000 --- a/doc/source/contributor/contributing.rst +++ /dev/null @@ -1,4 +0,0 @@ -============ -Contributing -============ -.. include:: ../../../CONTRIBUTING.rst diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 036e449..2aa0707 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -1,9 +1,4 @@ -=========================== - Contributor Documentation -=========================== - -.. toctree:: - :maxdepth: 2 - - contributing - +============ +Contributing +============ +.. include:: ../../../CONTRIBUTING.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index f4bf99a..b58067e 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -3,28 +3,19 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -=================================================== -Welcome to the documentation of os_resource_classes -=================================================== +=================== +os-resource-classes +=================== -Contents: +.. include:: ../../README.rst .. toctree:: - :maxdepth: 2 - readme install/index - library/index - contributor/index - configuration/index - cli/index user/index - admin/index - reference/index + contributor/index -Indices and tables -================== +Search +====== -* :ref:`genindex` -* :ref:`modindex` * :ref:`search` diff --git a/doc/source/install/common_configure.rst b/doc/source/install/common_configure.rst deleted file mode 100644 index 79d0e6f..0000000 --- a/doc/source/install/common_configure.rst +++ /dev/null @@ -1,10 +0,0 @@ -2. Edit the ``/etc/os_resource_classes/os_resource_classes.conf`` file and complete the following - actions: - - * In the ``[database]`` section, configure database access: - - .. code-block:: ini - - [database] - ... - connection = mysql+pymysql://os_resource_classes:OS_RESOURCE_CLASSES_DBPASS@controller/os_resource_classes diff --git a/doc/source/install/common_prerequisites.rst b/doc/source/install/common_prerequisites.rst deleted file mode 100644 index a600a56..0000000 --- a/doc/source/install/common_prerequisites.rst +++ /dev/null @@ -1,75 +0,0 @@ -Prerequisites -------------- - -Before you install and configure the Resource Classes for OpenStack service, -you must create a database, service credentials, and API endpoints. - -#. To create the database, complete these steps: - - * Use the database access client to connect to the database - server as the ``root`` user: - - .. code-block:: console - - $ mysql -u root -p - - * Create the ``os_resource_classes`` database: - - .. code-block:: none - - CREATE DATABASE os_resource_classes; - - * Grant proper access to the ``os_resource_classes`` database: - - .. code-block:: none - - GRANT ALL PRIVILEGES ON os_resource_classes.* TO 'os_resource_classes'@'localhost' \ - IDENTIFIED BY 'OS_RESOURCE_CLASSES_DBPASS'; - GRANT ALL PRIVILEGES ON os_resource_classes.* TO 'os_resource_classes'@'%' \ - IDENTIFIED BY 'OS_RESOURCE_CLASSES_DBPASS'; - - Replace ``OS_RESOURCE_CLASSES_DBPASS`` with a suitable password. - - * Exit the database access client. - - .. code-block:: none - - exit; - -#. Source the ``admin`` credentials to gain access to - admin-only CLI commands: - - .. code-block:: console - - $ . admin-openrc - -#. To create the service credentials, complete these steps: - - * Create the ``os_resource_classes`` user: - - .. code-block:: console - - $ openstack user create --domain default --password-prompt os_resource_classes - - * Add the ``admin`` role to the ``os_resource_classes`` user: - - .. code-block:: console - - $ openstack role add --project service --user os_resource_classes admin - - * Create the os_resource_classes service entities: - - .. code-block:: console - - $ openstack service create --name os_resource_classes --description "Resource Classes for OpenStack" resource classes for openstack - -#. Create the Resource Classes for OpenStack service API endpoints: - - .. code-block:: console - - $ openstack endpoint create --region RegionOne \ - resource classes for openstack public http://controller:XXXX/vY/%\(tenant_id\)s - $ openstack endpoint create --region RegionOne \ - resource classes for openstack internal http://controller:XXXX/vY/%\(tenant_id\)s - $ openstack endpoint create --region RegionOne \ - resource classes for openstack admin http://controller:XXXX/vY/%\(tenant_id\)s diff --git a/doc/source/install/get_started.rst b/doc/source/install/get_started.rst deleted file mode 100644 index 12b29be..0000000 --- a/doc/source/install/get_started.rst +++ /dev/null @@ -1,9 +0,0 @@ -=============================================== -Resource Classes for OpenStack service overview -=============================================== -The Resource Classes for OpenStack service provides... - -The Resource Classes for OpenStack service consists of the following components: - -``os_resource_classes-api`` service - Accepts and responds to end user compute API calls... diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index 049eaae..07085cd 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -1,17 +1,13 @@ -========================================================= -Resource Classes for OpenStack service installation guide -========================================================= +================== +Installation Guide +================== -.. toctree:: - :maxdepth: 2 +``os-resource-classes`` is availabe on `PyPI`_ and may be installed using +`pip`_:: - get_started.rst - install.rst - verify.rst - next-steps.rst + pip install os-resource-classes -The Resource Classes for OpenStack service (os_resource_classes) provides... +See :doc:`/user/index` for how to use it once it is installed. -This chapter assumes a working setup of OpenStack following the -`OpenStack Installation Tutorial -`_. +.. _PyPI: https://pypi.org/project/os-resource-classes/ +.. _pip: https://pypi.org/project/pip/ diff --git a/doc/source/install/install-obs.rst b/doc/source/install/install-obs.rst deleted file mode 100644 index feaee7a..0000000 --- a/doc/source/install/install-obs.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. _install-obs: - - -Install and configure for openSUSE and SUSE Linux Enterprise -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This section describes how to install and configure the Resource Classes for OpenStack service -for openSUSE Leap 42.1 and SUSE Linux Enterprise Server 12 SP1. - -.. include:: common_prerequisites.rst - -Install and configure components --------------------------------- - -#. Install the packages: - - .. code-block:: console - - # zypper --quiet --non-interactive install - -.. include:: common_configure.rst - - -Finalize installation ---------------------- - -Start the Resource Classes for OpenStack services and configure them to start when -the system boots: - -.. code-block:: console - - # systemctl enable openstack-os_resource_classes-api.service - - # systemctl start openstack-os_resource_classes-api.service diff --git a/doc/source/install/install-rdo.rst b/doc/source/install/install-rdo.rst deleted file mode 100644 index 839451f..0000000 --- a/doc/source/install/install-rdo.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. _install-rdo: - -Install and configure for Red Hat Enterprise Linux and CentOS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -This section describes how to install and configure the Resource Classes for OpenStack service -for Red Hat Enterprise Linux 7 and CentOS 7. - -.. include:: common_prerequisites.rst - -Install and configure components --------------------------------- - -#. Install the packages: - - .. code-block:: console - - # yum install - -.. include:: common_configure.rst - -Finalize installation ---------------------- - -Start the Resource Classes for OpenStack services and configure them to start when -the system boots: - -.. code-block:: console - - # systemctl enable openstack-os_resource_classes-api.service - - # systemctl start openstack-os_resource_classes-api.service diff --git a/doc/source/install/install-ubuntu.rst b/doc/source/install/install-ubuntu.rst deleted file mode 100644 index 44ed37b..0000000 --- a/doc/source/install/install-ubuntu.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _install-ubuntu: - -Install and configure for Ubuntu -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This section describes how to install and configure the Resource Classes for OpenStack -service for Ubuntu 14.04 (LTS). - -.. include:: common_prerequisites.rst - -Install and configure components --------------------------------- - -#. Install the packages: - - .. code-block:: console - - # apt-get update - - # apt-get install - -.. include:: common_configure.rst - -Finalize installation ---------------------- - -Restart the Resource Classes for OpenStack services: - -.. code-block:: console - - # service openstack-os_resource_classes-api restart diff --git a/doc/source/install/install.rst b/doc/source/install/install.rst deleted file mode 100644 index 2d8f1a6..0000000 --- a/doc/source/install/install.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _install: - -Install and configure -~~~~~~~~~~~~~~~~~~~~~ - -This section describes how to install and configure the -Resource Classes for OpenStack service, code-named os_resource_classes, on the controller node. - -This section assumes that you already have a working OpenStack -environment with at least the following components installed: -.. (add the appropriate services here and further notes) - -Note that installation and configuration vary by distribution. - -.. toctree:: - :maxdepth: 2 - - install-obs.rst - install-rdo.rst - install-ubuntu.rst diff --git a/doc/source/install/next-steps.rst b/doc/source/install/next-steps.rst deleted file mode 100644 index c8c1cfc..0000000 --- a/doc/source/install/next-steps.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _next-steps: - -Next steps -~~~~~~~~~~ - -Your OpenStack environment now includes the os_resource_classes service. - -To add additional services, see -https://docs.openstack.org/project-install-guide/ocata/. diff --git a/doc/source/install/verify.rst b/doc/source/install/verify.rst deleted file mode 100644 index ae5fb93..0000000 --- a/doc/source/install/verify.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. _verify: - -Verify operation -~~~~~~~~~~~~~~~~ - -Verify operation of the Resource Classes for OpenStack service. - -.. note:: - - Perform these commands on the controller node. - -#. Source the ``admin`` project credentials to gain access to - admin-only CLI commands: - - .. code-block:: console - - $ . admin-openrc - -#. List service components to verify successful launch and registration - of each process: - - .. code-block:: console - - $ openstack resource classes for openstack service list diff --git a/doc/source/library/index.rst b/doc/source/library/index.rst deleted file mode 100644 index e5423f5..0000000 --- a/doc/source/library/index.rst +++ /dev/null @@ -1,7 +0,0 @@ -======== -Usage -======== - -To use os-resource-classes in a project:: - - import os_resource_classes diff --git a/doc/source/readme.rst b/doc/source/readme.rst deleted file mode 100644 index a6210d3..0000000 --- a/doc/source/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../README.rst diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst deleted file mode 100644 index f51d16e..0000000 --- a/doc/source/reference/index.rst +++ /dev/null @@ -1,5 +0,0 @@ -========== -References -========== - -References of os-resource-classes. diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index 56cecdd..f44bfdf 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -1,5 +1,12 @@ -=========== -Users guide -=========== -Users guide of os-resource-classes. +===== +Usage +===== + +To use ``os-resource-classes`` in a project: + +.. code-block:: python + + import os_resource_classes as orc + + vcpu = orc.VPCU