From ab45cacbb6baf02087d0651b11c79b8874db0302 Mon Sep 17 00:00:00 2001 From: daz Date: Fri, 17 Jul 2015 14:55:29 +1000 Subject: [PATCH] Getting started chapter reorganisation 1. Split chapter file content into section files per current Cloud Admin Guide 2. Added cross-references Change-Id: I51025b6eb4bb9b8912871837f9ce83d91dca973d Implements: blueprint reorganise-user-guides --- doc/common-rst/get_started_block_storage.rst | 5 +- doc/common-rst/get_started_compute.rst | 5 +- .../get_started_conceptual_architecture.rst | 5 +- doc/common-rst/get_started_dashboard.rst | 6 +- .../get_started_database_service.rst | 5 +- doc/common-rst/get_started_feedback.rst | 10 +++ doc/common-rst/get_started_identity.rst | 5 +- doc/common-rst/get_started_image_service.rst | 15 ++-- .../get_started_logical_architecture.rst | 19 +++-- doc/common-rst/get_started_object_storage.rst | 5 +- .../get_started_openstack_networking.rst | 5 +- .../get_started_openstack_services.rst | 22 ++++++ doc/common-rst/get_started_orchestration.rst | 7 +- doc/common-rst/get_started_sahara.rst | 5 +- .../get_started_storage_concepts.rst | 5 +- doc/common-rst/get_started_telemetry.rst | 5 +- doc/common-rst/get_started_with_openstack.rst | 71 +++---------------- 17 files changed, 82 insertions(+), 118 deletions(-) create mode 100644 doc/common-rst/get_started_feedback.rst create mode 100644 doc/common-rst/get_started_openstack_services.rst diff --git a/doc/common-rst/get_started_block_storage.rst b/doc/common-rst/get_started_block_storage.rst index 4430a85439..b5afee00d9 100644 --- a/doc/common-rst/get_started_block_storage.rst +++ b/doc/common-rst/get_started_block_storage.rst @@ -1,7 +1,6 @@ -.. :orphan: - +======================= OpenStack Block Storage ------------------------ +======================= The OpenStack Block Storage service (cinder) adds persistent storage to a virtual machine. Block Storage provides an infrastructure for managing diff --git a/doc/common-rst/get_started_compute.rst b/doc/common-rst/get_started_compute.rst index 49e5fe91f6..7b796db7c2 100644 --- a/doc/common-rst/get_started_compute.rst +++ b/doc/common-rst/get_started_compute.rst @@ -1,7 +1,6 @@ -.. :orphan: - +================= OpenStack Compute ------------------ +================= Use OpenStack Compute to host and manage cloud computing systems. OpenStack Compute is a major part of an Infrastructure-as-a-Service diff --git a/doc/common-rst/get_started_conceptual_architecture.rst b/doc/common-rst/get_started_conceptual_architecture.rst index 342b2e4338..7fd0c5a96b 100644 --- a/doc/common-rst/get_started_conceptual_architecture.rst +++ b/doc/common-rst/get_started_conceptual_architecture.rst @@ -1,7 +1,8 @@ -.. :orphan: +.. _get_started_conceptual_architecture: +======================= Conceptual architecture -~~~~~~~~~~~~~~~~~~~~~~~ +======================= The following diagram shows the relationships among the OpenStack services: diff --git a/doc/common-rst/get_started_dashboard.rst b/doc/common-rst/get_started_dashboard.rst index b01a239a77..ef4d1058b2 100644 --- a/doc/common-rst/get_started_dashboard.rst +++ b/doc/common-rst/get_started_dashboard.rst @@ -1,7 +1,8 @@ -.. :orphan: +.. _get_started_dashboard: +=================== OpenStack dashboard -------------------- +=================== The OpenStack dashboard is a modular `Django web application `__ that provides a @@ -19,4 +20,3 @@ To use the administrator functionality for other services, it must also connect to Admin API endpoints, which should not be accessible by customers. - diff --git a/doc/common-rst/get_started_database_service.rst b/doc/common-rst/get_started_database_service.rst index 523f57dfb7..905ab7a243 100644 --- a/doc/common-rst/get_started_database_service.rst +++ b/doc/common-rst/get_started_database_service.rst @@ -1,7 +1,6 @@ -.. :orphan: - +========================== OpenStack Database service --------------------------- +========================== The Database service provides scalable and reliable cloud provisioning functionality for both relational and non-relational database engines. diff --git a/doc/common-rst/get_started_feedback.rst b/doc/common-rst/get_started_feedback.rst new file mode 100644 index 0000000000..f68aa77d32 --- /dev/null +++ b/doc/common-rst/get_started_feedback.rst @@ -0,0 +1,10 @@ +======== +Feedback +======== + +To provide feedback on documentation, join and use the +openstack-docs@lists.openstack.org mailing list at `OpenStack +Documentation Mailing +List `__, +or `report a +bug `__. diff --git a/doc/common-rst/get_started_identity.rst b/doc/common-rst/get_started_identity.rst index 237bb8a580..48b535348e 100644 --- a/doc/common-rst/get_started_identity.rst +++ b/doc/common-rst/get_started_identity.rst @@ -1,7 +1,6 @@ -.. :orphan: - +================== OpenStack Identity ------------------- +================== The OpenStack Identity service performs the following functions: diff --git a/doc/common-rst/get_started_image_service.rst b/doc/common-rst/get_started_image_service.rst index 47ce847e70..d80a0502b4 100644 --- a/doc/common-rst/get_started_image_service.rst +++ b/doc/common-rst/get_started_image_service.rst @@ -1,15 +1,12 @@ -.. :orphan: - +======================= OpenStack Image service ------------------------ +======================= The OpenStack Image service is central to Infrastructure-as-a-Service -(IaaS) as shown in Conceptual architecture. It accepts API requests for disk -or server images, and image metadata from end users or OpenStack Compute -components. It also supports the storage of disk or server images on various -repository types, including OpenStack Object Storage. - -.. TODO (DC) On line 7, add link to get_started_conceptual_architecture.rst +(IaaS) as shown in :ref:`get_started_conceptual_architecture`. It accepts API +requests for disk or server images, and image metadata from end users or +OpenStack Compute components. It also supports the storage of disk or server +images on various repository types, including OpenStack Object Storage. A number of periodic processes run on the OpenStack Image service to support caching. Replication services ensure consistency and diff --git a/doc/common-rst/get_started_logical_architecture.rst b/doc/common-rst/get_started_logical_architecture.rst index 280bdbcff7..3c191e6bcc 100644 --- a/doc/common-rst/get_started_logical_architecture.rst +++ b/doc/common-rst/get_started_logical_architecture.rst @@ -1,18 +1,15 @@ -.. :orphan: - +==================== Logical architecture -~~~~~~~~~~~~~~~~~~~~ +==================== To design, deploy, and configure OpenStack, administrators must understand the logical architecture. -As shown in Conceptual architecture, OpenStack consists of several -independent parts, named the OpenStack services. All services authenticate -through a common Identity service. Individual services interact with each -other through public APIs, except where privileged administrator commands -are necessary. - -.. TODO (DC) Add link to figure in get_started_conceptual_architecture.rst +As shown in :ref:`get_started_conceptual_architecture`, OpenStack consists of +several independent parts, named the OpenStack services. All services +authenticate through a common Identity service. Individual services interact +with each other through public APIs, except where privileged administrator +commands are necessary. Internally, OpenStack services are composed of several processes. All services have at least one API process, which listens for API requests, @@ -27,7 +24,7 @@ several message broker and database solutions, such as RabbitMQ, Qpid, MySQL, MariaDB, and SQLite. Users can access OpenStack via the web-based user interface implemented -by the OpenStack dashboard, via `command-line +by the :ref:`get_started_dashboard`, via `command-line clients `__ and by issuing API requests through tools like browser plug-ins or :command:`curl`. For applications, `several SDKs `__ diff --git a/doc/common-rst/get_started_object_storage.rst b/doc/common-rst/get_started_object_storage.rst index 2fe4abff36..37b33d0e15 100644 --- a/doc/common-rst/get_started_object_storage.rst +++ b/doc/common-rst/get_started_object_storage.rst @@ -1,7 +1,6 @@ -.. :orphan: - +======================== OpenStack Object Storage ------------------------- +======================== The OpenStack Object Storage is a multi-tenant object storage system. It is highly scalable and can manage large amounts of unstructured data at diff --git a/doc/common-rst/get_started_openstack_networking.rst b/doc/common-rst/get_started_openstack_networking.rst index 19fbaec01c..18c6eb5b1c 100644 --- a/doc/common-rst/get_started_openstack_networking.rst +++ b/doc/common-rst/get_started_openstack_networking.rst @@ -1,7 +1,6 @@ -.. :orphan: - +==================== OpenStack Networking --------------------- +==================== OpenStack Networking (neutron) allows you to create and attach interface devices managed by other OpenStack services to networks. Plug-ins can be diff --git a/doc/common-rst/get_started_openstack_services.rst b/doc/common-rst/get_started_openstack_services.rst new file mode 100644 index 0000000000..05f6425f8f --- /dev/null +++ b/doc/common-rst/get_started_openstack_services.rst @@ -0,0 +1,22 @@ +================== +OpenStack services +================== + +.. toctree:: + :maxdepth: 2 + + + get_started_compute.rst + get_started_storage_concepts.rst + get_started_object_storage.rst + get_started_block_storage.rst + get_started_openstack_networking.rst + get_started_dashboard.rst + get_started_identity.rst + get_started_image_service.rst + get_started_telemetry.rst + get_started_orchestration.rst + get_started_database_service.rst + get_started_sahara.rst + +This section describes OpenStack services in detail. diff --git a/doc/common-rst/get_started_orchestration.rst b/doc/common-rst/get_started_orchestration.rst index 6fecc88578..77155469ae 100644 --- a/doc/common-rst/get_started_orchestration.rst +++ b/doc/common-rst/get_started_orchestration.rst @@ -1,10 +1,9 @@ -.. :orphan: - +============================== OpenStack Orchestration module ------------------------------- +============================== The Orchestration module provides a template-based orchestration for -describing a cloud application, by running OpenStack API calls to +describing a cloud application by running OpenStack API calls to generate running cloud applications. The software integrates other core components of OpenStack into a one-file template system. The templates allow you to create most OpenStack resource types, such as instances, diff --git a/doc/common-rst/get_started_sahara.rst b/doc/common-rst/get_started_sahara.rst index dfdc1a13a9..8f555e1dfa 100644 --- a/doc/common-rst/get_started_sahara.rst +++ b/doc/common-rst/get_started_sahara.rst @@ -1,7 +1,8 @@ .. :orphan: +================================= OpenStack Data processing service ---------------------------------- +================================= The Data processing service for OpenStack (sahara) aims to provide users with a simple means to provision data processing (Hadoop, Spark) @@ -9,7 +10,7 @@ clusters by specifying several parameters like Hadoop version, cluster topology, node hardware details and a few more. After a user fills in all the parameters, the Data processing service deploys the cluster in a few minutes. Sahara also provides a means to scale already provisioned -clusters by adding/removing worker nodes on demand. +clusters by adding or removing worker nodes on demand. The solution addresses the following use cases: diff --git a/doc/common-rst/get_started_storage_concepts.rst b/doc/common-rst/get_started_storage_concepts.rst index faef91ddfa..c1f2375db0 100644 --- a/doc/common-rst/get_started_storage_concepts.rst +++ b/doc/common-rst/get_started_storage_concepts.rst @@ -1,7 +1,6 @@ -.. :orphan: - +================ Storage concepts ----------------- +================ The OpenStack stack uses the following storage types: diff --git a/doc/common-rst/get_started_telemetry.rst b/doc/common-rst/get_started_telemetry.rst index 79f46a16e7..f53918d9de 100644 --- a/doc/common-rst/get_started_telemetry.rst +++ b/doc/common-rst/get_started_telemetry.rst @@ -1,7 +1,6 @@ -.. :orphan: - +========================== OpenStack Telemetry module --------------------------- +========================== The Telemetry module performs the following functions: diff --git a/doc/common-rst/get_started_with_openstack.rst b/doc/common-rst/get_started_with_openstack.rst index c48cd128a1..b196fe2244 100644 --- a/doc/common-rst/get_started_with_openstack.rst +++ b/doc/common-rst/get_started_with_openstack.rst @@ -4,6 +4,14 @@ Get started with OpenStack ========================== +.. toctree:: + :maxdepth: 2 + + get_started_conceptual_architecture.rst + get_started_logical_architecture.rst + get_started_openstack_services.rst + get_started_feedback.rst + The OpenStack project is an open source cloud computing platform for all types of clouds, which aims to be simple to implement, massively scalable, and feature rich. Developers and cloud computing technologists @@ -83,66 +91,3 @@ OpenStack architecture: by specifying parameters like Hadoop version, cluster topology and nodes hardware details. -.. include:: get_started_conceptual_architecture.rst -.. include:: get_started_logical_architecture.rst - -.. toctree:: - :hidden: - - get_started_conceptual_architecture.rst - get_started_logical_architecture.rst - -OpenStack services -~~~~~~~~~~~~~~~~~~ - -This section describes OpenStack services in detail. - -.. include:: get_started_compute.rst - -.. include:: get_started_storage_concepts.rst - -.. include:: get_started_object_storage.rst - -.. include:: get_started_block_storage.rst - -.. include:: get_started_openstack_networking.rst - -.. include:: get_started_dashboard.rst - -.. include:: get_started_identity.rst - -.. include:: get_started_image_service.rst - -.. include:: get_started_telemetry.rst - -.. include:: get_started_orchestration.rst - -.. include:: get_started_database_service.rst - -.. include:: get_started_sahara.rst - -.. toctree:: - :hidden: - - get_started_compute.rst - get_started_storage_concepts.rst - get_started_object_storage.rst - get_started_block_storage.rst - get_started_openstack_networking.rst - get_started_dashboard.rst - get_started_identity.rst - get_started_image_service.rst - get_started_telemetry.rst - get_started_orchestration.rst - get_started_database_service.rst - get_started_sahara.rst - -Feedback -~~~~~~~~ - -To provide feedback on documentation, join and use the -openstack-docs@lists.openstack.org mailing list at `OpenStack -Documentation Mailing -List `__, -or `report a -bug `__.