From c960f2609894c64d49334972e2a7682c3de6b63b Mon Sep 17 00:00:00 2001 From: csatari Date: Tue, 11 Jul 2017 12:00:15 +0200 Subject: [PATCH] Update to the Pike document structure In this change the documents folder changed in the following way: - Folder structure follows the Pike structure defined in [1] - Structure of Install guide is added as it is moved into the doc folder. [1]: http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html Change-Id: Ia58725958d64fba81a5c4661b2686cd643eaa426 Depends-On: Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454 Signed-off-by: csatari --- cookiecutter.json | 1 + .../doc/source/admin/index.rst | 5 ++ .../doc/source/cli/index.rst | 5 ++ .../doc/source/configuration/index.rst | 5 ++ .../doc/source/index.rst | 19 ++++- .../doc/source/install/common_configure.rst | 10 +++ .../source/install/common_prerequisites.rst | 75 +++++++++++++++++++ .../doc/source/install/get_started.rst | 16 ++++ .../doc/source/install/index.rst | 28 +++++-- .../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/reference/index.rst | 5 ++ .../doc/source/user/index.rst | 5 ++ 17 files changed, 314 insertions(+), 11 deletions(-) create mode 100644 {{cookiecutter.repo_name}}/doc/source/admin/index.rst create mode 100644 {{cookiecutter.repo_name}}/doc/source/cli/index.rst create mode 100644 {{cookiecutter.repo_name}}/doc/source/configuration/index.rst create mode 100644 {{cookiecutter.repo_name}}/doc/source/install/common_configure.rst create mode 100644 {{cookiecutter.repo_name}}/doc/source/install/common_prerequisites.rst create mode 100644 {{cookiecutter.repo_name}}/doc/source/install/get_started.rst create mode 100644 {{cookiecutter.repo_name}}/doc/source/install/install-obs.rst create mode 100644 {{cookiecutter.repo_name}}/doc/source/install/install-rdo.rst create mode 100644 {{cookiecutter.repo_name}}/doc/source/install/install-ubuntu.rst create mode 100644 {{cookiecutter.repo_name}}/doc/source/install/install.rst create mode 100644 {{cookiecutter.repo_name}}/doc/source/install/next-steps.rst create mode 100644 {{cookiecutter.repo_name}}/doc/source/install/verify.rst create mode 100644 {{cookiecutter.repo_name}}/doc/source/reference/index.rst create mode 100644 {{cookiecutter.repo_name}}/doc/source/user/index.rst diff --git a/cookiecutter.json b/cookiecutter.json index dd0a675..eb1cdbd 100644 --- a/cookiecutter.json +++ b/cookiecutter.json @@ -1,5 +1,6 @@ { "module_name": "replace with the name of the python module", + "service": "replace with the service it implements", "repo_group": "openstack", "repo_name": "replace with the name for the git repo", "launchpad_project": "replace with the name of the project on launchpad", diff --git a/{{cookiecutter.repo_name}}/doc/source/admin/index.rst b/{{cookiecutter.repo_name}}/doc/source/admin/index.rst new file mode 100644 index 0000000..1173997 --- /dev/null +++ b/{{cookiecutter.repo_name}}/doc/source/admin/index.rst @@ -0,0 +1,5 @@ +==================== +Administrators guide +==================== + +Administrators guide of {{ cookiecutter.repo_name }}. diff --git a/{{cookiecutter.repo_name}}/doc/source/cli/index.rst b/{{cookiecutter.repo_name}}/doc/source/cli/index.rst new file mode 100644 index 0000000..de2256e --- /dev/null +++ b/{{cookiecutter.repo_name}}/doc/source/cli/index.rst @@ -0,0 +1,5 @@ +================================ +Command line interface reference +================================ + +CLI reference of {{ cookiecutter.repo_name }}. diff --git a/{{cookiecutter.repo_name}}/doc/source/configuration/index.rst b/{{cookiecutter.repo_name}}/doc/source/configuration/index.rst new file mode 100644 index 0000000..cd7f535 --- /dev/null +++ b/{{cookiecutter.repo_name}}/doc/source/configuration/index.rst @@ -0,0 +1,5 @@ +============= +Configuration +============= + +Configuration of {{ cookiecutter.repo_name }}. diff --git a/{{cookiecutter.repo_name}}/doc/source/index.rst b/{{cookiecutter.repo_name}}/doc/source/index.rst index 2dac780..18ec348 100644 --- a/{{cookiecutter.repo_name}}/doc/source/index.rst +++ b/{{cookiecutter.repo_name}}/doc/source/index.rst @@ -1,10 +1,19 @@ +{%- macro set_header_markup(header_text_length) -%} +{%- set module_name_length = cookiecutter.module_name|length -%} +{%- for _ in range(0, module_name_length + header_text_length) -%}={%- endfor -%} +{%- endmacro -%} +{%- macro set_header(header_text) -%} +{{ set_header_markup(header_text|length) }} +{{header_text}}{{cookiecutter.module_name}} +{{ set_header_markup(header_text|length) }} +{%- endmacro -%} + .. {{ cookiecutter.repo_name }} documentation master file, created by sphinx-quickstart on Tue Jul 9 22:26:36 2013. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to {{ cookiecutter.repo_name }}'s documentation! -======================================================== +{{ set_header("Welcome to the documentation of ") }} Contents: @@ -15,6 +24,11 @@ Contents: install/index library/index contributor/index + configuration/index + cli/index + user/index + admin/index + reference/index Indices and tables ================== @@ -22,4 +36,3 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` - diff --git a/{{cookiecutter.repo_name}}/doc/source/install/common_configure.rst b/{{cookiecutter.repo_name}}/doc/source/install/common_configure.rst new file mode 100644 index 0000000..7af7956 --- /dev/null +++ b/{{cookiecutter.repo_name}}/doc/source/install/common_configure.rst @@ -0,0 +1,10 @@ +2. Edit the ``/etc/{{cookiecutter.module_name}}/{{cookiecutter.module_name}}.conf`` file and complete the following + actions: + + * In the ``[database]`` section, configure database access: + + .. code-block:: ini + + [database] + ... + connection = mysql+pymysql://{{cookiecutter.module_name}}:{{cookiecutter.module_name|upper}}_DBPASS@controller/{{cookiecutter.module_name}} diff --git a/{{cookiecutter.repo_name}}/doc/source/install/common_prerequisites.rst b/{{cookiecutter.repo_name}}/doc/source/install/common_prerequisites.rst new file mode 100644 index 0000000..babb278 --- /dev/null +++ b/{{cookiecutter.repo_name}}/doc/source/install/common_prerequisites.rst @@ -0,0 +1,75 @@ +Prerequisites +------------- + +Before you install and configure the {{cookiecutter.service}} 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 ``{{cookiecutter.module_name}}`` database: + + .. code-block:: none + + CREATE DATABASE {{cookiecutter.module_name}}; + + * Grant proper access to the ``{{cookiecutter.module_name}}`` database: + + .. code-block:: none + + GRANT ALL PRIVILEGES ON {{cookiecutter.module_name}}.* TO '{{cookiecutter.module_name}}'@'localhost' \ + IDENTIFIED BY '{{cookiecutter.module_name|upper}}_DBPASS'; + GRANT ALL PRIVILEGES ON {{cookiecutter.module_name}}.* TO '{{cookiecutter.module_name}}'@'%' \ + IDENTIFIED BY '{{cookiecutter.module_name|upper}}_DBPASS'; + + Replace ``{{cookiecutter.module_name|upper}}_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 ``{{cookiecutter.module_name}}`` user: + + .. code-block:: console + + $ openstack user create --domain default --password-prompt {{cookiecutter.module_name}} + + * Add the ``admin`` role to the ``{{cookiecutter.module_name}}`` user: + + .. code-block:: console + + $ openstack role add --project service --user {{cookiecutter.module_name}} admin + + * Create the {{cookiecutter.module_name}} service entities: + + .. code-block:: console + + $ openstack service create --name {{cookiecutter.module_name}} --description "{{cookiecutter.service}}" {{cookiecutter.service|lower}} + +#. Create the {{cookiecutter.service}} service API endpoints: + + .. code-block:: console + + $ openstack endpoint create --region RegionOne \ + {{cookiecutter.service|lower}} public http://controller:XXXX/vY/%\(tenant_id\)s + $ openstack endpoint create --region RegionOne \ + {{cookiecutter.service|lower}} internal http://controller:XXXX/vY/%\(tenant_id\)s + $ openstack endpoint create --region RegionOne \ + {{cookiecutter.service|lower}} admin http://controller:XXXX/vY/%\(tenant_id\)s diff --git a/{{cookiecutter.repo_name}}/doc/source/install/get_started.rst b/{{cookiecutter.repo_name}}/doc/source/install/get_started.rst new file mode 100644 index 0000000..43e243a --- /dev/null +++ b/{{cookiecutter.repo_name}}/doc/source/install/get_started.rst @@ -0,0 +1,16 @@ +{%- macro set_header_markup(header_text_length) -%} +{%- set servicelength = cookiecutter.service|length -%} +{%- for _ in range(0, servicelength + header_text_length) -%}={%- endfor -%} +{%- endmacro -%} +{%- macro set_header(header_text) -%} +{{ set_header_markup(header_text|length) }} +{{cookiecutter.service}}{{header_text}} +{{ set_header_markup(header_text|length) }} +{%- endmacro -%} +{{ set_header(" service overview") }} +The {{cookiecutter.service}} service provides... + +The {{cookiecutter.service}} service consists of the following components: + +``{{cookiecutter.module_name}}-api`` service + Accepts and responds to end user compute API calls... diff --git a/{{cookiecutter.repo_name}}/doc/source/install/index.rst b/{{cookiecutter.repo_name}}/doc/source/install/index.rst index 98401a0..4a53909 100644 --- a/{{cookiecutter.repo_name}}/doc/source/install/index.rst +++ b/{{cookiecutter.repo_name}}/doc/source/install/index.rst @@ -1,12 +1,24 @@ -============ -Installation -============ +{%- macro set_header_markup(header_text_length) -%} +{%- set servicelength = cookiecutter.service|length -%} +{%- for _ in range(0, servicelength + header_text_length) -%}={%- endfor -%} +{%- endmacro -%} +{%- macro set_header(header_text) -%} +{{ set_header_markup(header_text|length) }} +{{cookiecutter.service}}{{header_text}} +{{ set_header_markup(header_text|length) }} +{%- endmacro -%} +{{ set_header(" service installation guide") }} -At the command line:: +.. toctree:: + :maxdepth: 2 - $ pip install {{ cookiecutter.repo_name }} + get_started.rst + install.rst + verify.rst + next-steps.rst -Or, if you have virtualenvwrapper installed:: +The {{cookiecutter.service}} service ({{cookiecutter.module_name}}) provides... - $ mkvirtualenv {{ cookiecutter.repo_name }} - $ pip install {{ cookiecutter.repo_name }} +This chapter assumes a working setup of OpenStack following the +`OpenStack Installation Tutorial +`_. diff --git a/{{cookiecutter.repo_name}}/doc/source/install/install-obs.rst b/{{cookiecutter.repo_name}}/doc/source/install/install-obs.rst new file mode 100644 index 0000000..0089407 --- /dev/null +++ b/{{cookiecutter.repo_name}}/doc/source/install/install-obs.rst @@ -0,0 +1,34 @@ +.. _install-obs: + + +Install and configure for openSUSE and SUSE Linux Enterprise +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the {{cookiecutter.service}} 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 {{cookiecutter.service}} services and configure them to start when +the system boots: + +.. code-block:: console + + # systemctl enable openstack-{{cookiecutter.module_name}}-api.service + + # systemctl start openstack-{{cookiecutter.module_name}}-api.service diff --git a/{{cookiecutter.repo_name}}/doc/source/install/install-rdo.rst b/{{cookiecutter.repo_name}}/doc/source/install/install-rdo.rst new file mode 100644 index 0000000..4408602 --- /dev/null +++ b/{{cookiecutter.repo_name}}/doc/source/install/install-rdo.rst @@ -0,0 +1,33 @@ +.. _install-rdo: + +Install and configure for Red Hat Enterprise Linux and CentOS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +This section describes how to install and configure the {{cookiecutter.service}} 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 {{cookiecutter.service}} services and configure them to start when +the system boots: + +.. code-block:: console + + # systemctl enable openstack-{{cookiecutter.module_name}}-api.service + + # systemctl start openstack-{{cookiecutter.module_name}}-api.service diff --git a/{{cookiecutter.repo_name}}/doc/source/install/install-ubuntu.rst b/{{cookiecutter.repo_name}}/doc/source/install/install-ubuntu.rst new file mode 100644 index 0000000..415e988 --- /dev/null +++ b/{{cookiecutter.repo_name}}/doc/source/install/install-ubuntu.rst @@ -0,0 +1,31 @@ +.. _install-ubuntu: + +Install and configure for Ubuntu +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the {{cookiecutter.service}} +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 {{cookiecutter.service}} services: + +.. code-block:: console + + # service openstack-{{cookiecutter.module_name}}-api restart diff --git a/{{cookiecutter.repo_name}}/doc/source/install/install.rst b/{{cookiecutter.repo_name}}/doc/source/install/install.rst new file mode 100644 index 0000000..c051948 --- /dev/null +++ b/{{cookiecutter.repo_name}}/doc/source/install/install.rst @@ -0,0 +1,20 @@ +.. _install: + +Install and configure +~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the +{{cookiecutter.service}} service, code-named {{cookiecutter.module_name}}, 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/{{cookiecutter.repo_name}}/doc/source/install/next-steps.rst b/{{cookiecutter.repo_name}}/doc/source/install/next-steps.rst new file mode 100644 index 0000000..f024292 --- /dev/null +++ b/{{cookiecutter.repo_name}}/doc/source/install/next-steps.rst @@ -0,0 +1,9 @@ +.. _next-steps: + +Next steps +~~~~~~~~~~ + +Your OpenStack environment now includes the {{cookiecutter.module_name}} service. + +To add additional services, see +https://docs.openstack.org/project-install-guide/ocata/. diff --git a/{{cookiecutter.repo_name}}/doc/source/install/verify.rst b/{{cookiecutter.repo_name}}/doc/source/install/verify.rst new file mode 100644 index 0000000..378f7c0 --- /dev/null +++ b/{{cookiecutter.repo_name}}/doc/source/install/verify.rst @@ -0,0 +1,24 @@ +.. _verify: + +Verify operation +~~~~~~~~~~~~~~~~ + +Verify operation of the {{cookiecutter.service}} 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 {{cookiecutter.service|lower}} service list diff --git a/{{cookiecutter.repo_name}}/doc/source/reference/index.rst b/{{cookiecutter.repo_name}}/doc/source/reference/index.rst new file mode 100644 index 0000000..67ccac0 --- /dev/null +++ b/{{cookiecutter.repo_name}}/doc/source/reference/index.rst @@ -0,0 +1,5 @@ +========== +References +========== + +References of {{ cookiecutter.repo_name }}. diff --git a/{{cookiecutter.repo_name}}/doc/source/user/index.rst b/{{cookiecutter.repo_name}}/doc/source/user/index.rst new file mode 100644 index 0000000..42d7fdc --- /dev/null +++ b/{{cookiecutter.repo_name}}/doc/source/user/index.rst @@ -0,0 +1,5 @@ +=========== +Users guide +=========== + +Users guide of {{ cookiecutter.repo_name }}.