- Block Storage

- exclude common dir
k0ka · Jan 30, 2024 · Jan 17, 2024 · Jan 17, 2024 · Jan 17, 2024 · Jan 17, 2024
commit 090571a4720751cd683e7984b4221d0054cf38ca
diff --git a/doc/conf.py b/doc/conf.py
@@ -38,7 +38,7 @@
 copyright = u'2015-2023, PHP OpenCloud & contributors'
 version = '1.12'
 release = '1.12.1'
-exclude_patterns = ['_build']
+exclude_patterns = ['_build', 'common']
 pygments_style = 'sphinx'
 
 html_theme = 'sphinx_rtd_theme'

diff --git a/doc/services/block-storage/v2/index.rst b/doc/services/block-storage/v2/index.rst
@@ -6,4 +6,4 @@ It is recommended to use Block Storage v3 API instead. However most of endpoints
 to use Block Storage v2 API, you can use the change `$openstack->blockStorageV3()` to `$openstack->blockStorageV2()` in examples.
 In most cases it will work without any other changes.
 
-.. sample:: BlockStorage/v2/create_service.php
+.. sample:: BlockStorage/v2/create.php
diff --git a/doc/services/block-storage/v3/create.rst b/doc/services/block-storage/v3/create.rst
@@ -0,0 +1,12 @@
+Create Service
+==============
+
+In order to work with the service you have to :doc:`setup the client </setup>` first.
+
+Service can be created via ``blockStorageV3()`` method of the ``OpenStack`` object.
+
+.. sample:: BlockStorage/v3/create.php
+
+A list of additional options can be passed to the method. For example, to change the region:
+
+.. sample:: BlockStorage/v3/create_with_region.php
diff --git a/doc/services/block-storage/v3/index.rst b/doc/services/block-storage/v3/index.rst
@@ -2,8 +2,9 @@ Block Storage v3
 ================
 
 .. toctree::
-   :maxdepth: 3
+    :maxdepth: 3
 
-   volumes
-   volume-types
-   snapshots
+    create
+    volumes
+    volume-types
+    snapshots
diff --git a/doc/services/block-storage/v3/snapshots.rst b/doc/services/block-storage/v3/snapshots.rst
@@ -1,18 +1,26 @@
 Snapshots
 =========
 
-List volumes
-------------
+a read-only point in time copy of a volume. The snapshot can be created from a volume that is currently in use
+or in an available state. The snapshot can then be used to create a new volume.
+
+.. osdoc:: https://docs.openstack.org/api-ref/block-storage/v3/#volume-snapshots-snapshots
+
+.. |models| replace:: snapshots
+
+.. include:: /common/service.rst
+
+List
+----
 
 .. sample:: BlockStorage/v3/snapshots/list.php
-.. refdoc:: OpenStack/BlockStorage/v2/Service.html#method_listSnapshots
 
 Each iteration will return a php:class:`Snapshot` instance <OpenStack/BlockStorage/v2/Models/Snapshot.html>.
 
 .. include:: /common/generators.rst
 
-List volumes sorted
-~~~~~~~~~~~~~~~~~~~
+List sorted
+~~~~~~~~~~~
 
 Possible values for sort_key are:
 

diff --git a/doc/services/block-storage/v3/volume-types.rst b/doc/services/block-storage/v3/volume-types.rst
@@ -1,59 +1,45 @@
 Volume Types
 ============
 
-Listing volume types
---------------------
-.. sample:: BlockStorage/v3/volume_types/list.php
-.. refdoc:: OpenStack/BlockStorage/v2/Service.html#method_listVolumeTypes
+Volume type is a group of volume policies. They can be used to specify which driver must be used on volume creation.
 
-Each iteration will return a :php:class:`VolumeType` instance <OpenStack/BlockStorage/v2/Models/VolumeType.html>.
+.. osdoc:: https://docs.openstack.org/api-ref/block-storage/v3/#volumes-volumes
 
-.. include:: /common/generators.rst
+.. |models| replace:: volume types
 
+.. include:: /common/service.rst
 
-Create volume type
-------------------
+Create
+------
 
-The only attributes that are required when creating a volume are a name. The simplest example
-would therefore be this:
+The only attributes that are required when creating a volume are a name.
 
 .. sample:: BlockStorage/v3/volume_types/create.php
-.. refdoc:: OpenStack/BlockStorage/v2/Service.html#method_createVolumeType
-
-
-Retrieve details of a volume type
----------------------------------
-
-When retrieving a volume type, sometimes you only want to operate on it - say to update or delete it. If this is the
-case, then there is no need to perform an initial GET request to the API:
-
-.. sample:: BlockStorage/v3/volume_types/get.php
-
-If, however, you *do* want to retrieve all the details of a remote volume type from the API, you just call:
 
-.. code-block:: php
 
-    $volumeType->retrieve();
+Read
+----
 
-which will update the state of the local object. This gives you an element of control over your app's performance.
+.. sample:: BlockStorage/v3/volume_types/read.php
 
-.. refdoc:: OpenStack/BlockStorage/v2/Service.html#method_getVolumeType
 
-
-Update a volume type
---------------------
-
-The first step when updating a volume type is modifying the attributes you want updated. By default, only a volume
-type's name can be edited.
+Update
+------
 
 .. sample:: BlockStorage/v3/volume_types/update.php
-.. refdoc:: OpenStack/BlockStorage/v2/Models/VolumeType.html#method_update
 
 
-Delete volume type
-------------------
+Delete
+------
 
 To permanently delete a volume type:
 
 .. sample:: BlockStorage/v3/volume_types/delete.php
-.. refdoc:: OpenStack/BlockStorage/v2/Models/VolumeType.html#method_delete
+
+List
+----
+.. sample:: BlockStorage/v3/volume_types/list.php
+
+Each iteration will return a :php:class:`VolumeType` instance <OpenStack/BlockStorage/v2/Models/VolumeType.html>.
+
+.. include:: /common/generators.rst
diff --git a/doc/services/block-storage/v3/volumes.rst b/doc/services/block-storage/v3/volumes.rst
@@ -1,26 +1,17 @@
 Volumes
 =======
 
-List volumes
-------------
+A volume is a detachable block storage device similar to a USB hard drive. You can attach a volume to an instance, and
+if the volume is of an appropriate volume type, a volume can be attached to multiple instances.
 
-.. sample:: BlockStorage/v3/volumes/list.php
-.. refdoc:: OpenStack/BlockStorage/v2/Service.html#method_listVolumes
-
-Each iteration will return a php:class:`Volume` instance <OpenStack/BlockStorage/v2/Models/Volume.html>.
+.. osdoc:: https://docs.openstack.org/api-ref/block-storage/v3/#volumes-volumes
 
-.. include:: /common/generators.rst
+.. |models| replace:: volumes
 
-Detailed information
-~~~~~~~~~~~~~~~~~~~~
+.. include:: /common/service.rst
 
-By default, only the ``id``, ``links`` and ``name`` attributes are returned. To return *all* information
-for a flavor, you must enable detailed information, like so:
-
-.. sample:: BlockStorage/v3/volumes/list_detail.php
-
-Create volume
--------------
+Create
+------
 
 The only attributes that are required when creating a volume are a size in GiB. The simplest example
 would therefore be this:
@@ -30,8 +21,6 @@ would therefore be this:
 You can further configure your new volume, however, by following the below sections, which instruct you how to add
 specific functionality.
 
-.. refdoc:: OpenStack/BlockStorage/v2/Service.html#method_createVolume
-
 Create from image
 ~~~~~~~~~~~~~~~~~
 
@@ -42,44 +31,46 @@ Create from snapshot
 
 .. sample:: BlockStorage/v3/volumes/create_from_snapshot.php
 
-Create from source volume
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. sample:: BlockStorage/v3/volumes/create_from_source_volume.php
+Create from volume
+~~~~~~~~~~~~~~~~~~
 
+.. sample:: BlockStorage/v3/volumes/create_from_volume.php
 
-Retrieve volume details
------------------------
 
-When retrieving a volume, sometimes you only want to operate on it - say to update or delete it. If this is the case,
-then there is no need to perform an initial GET request to the API:
+Read
+----
 
 .. sample:: BlockStorage/v3/volumes/get.php
 
-If, however, you *do* want to retrieve all the details of a remote volume from the API, you just call:
 
-.. code-block:: php
+Update
+------
 
-    $volume->retrieve();
+The first step when updating a volume is modifying the attributes you want updated. Only a volume's name
+and description can be edited.
 
-which will update the state of the local object. This gives you an element of control over your app's performance.
+.. sample:: BlockStorage/v3/volumes/update.php
 
-.. refdoc:: OpenStack/BlockStorage/v2/Service.html#method_getVolume
+Delete
+------
 
+To permanently delete a volume:
 
-Update volume
--------------
+.. sample:: BlockStorage/v3/volumes/delete.php
 
-The first step when updating a volume is modifying the attributes you want updated. By default, only a volume's name
-and description can be edited.
+List
+----
 
-.. sample:: BlockStorage/v3/volumes/update.php
-.. refdoc:: OpenStack/BlockStorage/v2/Models/Volume.html#method_update
+.. sample:: BlockStorage/v3/volumes/list.php
 
-Delete volume
--------------
+Each iteration will return a php:class:`Volume` instance <OpenStack/BlockStorage/v2/Models/Volume.html>.
 
-To permanently delete a volume:
+.. include:: /common/generators.rst
 
-.. sample:: BlockStorage/v3/volumes/delete.php
-.. refdoc:: OpenStack/BlockStorage/v2/Models/Volume.html#method_delete
+Detailed information
+~~~~~~~~~~~~~~~~~~~~
+
+By default, only the ``id``, ``links`` and ``name`` attributes are returned. To return *all* information
+for a flavor, you must enable detailed information:
+
+.. sample:: BlockStorage/v3/volumes/list_detail.php
diff --git a/doc/services/identity/v3/create.rst b/doc/services/identity/v3/create.rst
@@ -6,9 +6,7 @@ In order to work with the service you have to :doc:`setup the client </setup>` f
 Service can be created via ``identityV3()`` method of the ``OpenStack`` object.
 
 .. sample:: Identity/v3/create.php
-    :full:
 
 A list of additional options can be passed to the method. For example, to change the region:
 
 .. sample:: Identity/v3/create_with_region.php
-    :full:
diff --git a/doc/setup.rst b/doc/setup.rst
@@ -26,7 +26,7 @@ as usernames will not be unique across an entire OpenStack installation
 .. sample:: Setup/username.php
 
 Authenticate with user ID
---------------------------
+-------------------------
 
 .. sample:: Setup/user_id.php
 
@@ -36,7 +36,7 @@ Authenticate application credential ID
 .. sample:: Setup/application_credential_id.php
 
 Authenticate using token ID
---------------------------
+---------------------------
 
 If you already have a valid token, you can use it to authenticate.
 

diff --git a/samples/BlockStorage/v2/create.php b/samples/BlockStorage/v2/create.php
@@ -0,0 +1,14 @@
+<?php
+
+require 'vendor/autoload.php';
+
+$openstack = new OpenStack\OpenStack([
+    'authUrl' => '{authUrl}',
+    'region'  => '{region}',
+    'user'    => [
+        'id'       => '{userId}',
+        'password' => '{password}',
+    ],
+]);
+
+$service = $openstack->blockStorageV2();
diff --git a/samples/BlockStorage/v2/create_service.php b/samples/BlockStorage/v2/create_service.php
diff --git a/samples/BlockStorage/v3/create.php b/samples/BlockStorage/v3/create.php
@@ -0,0 +1,14 @@
+<?php
+
+require 'vendor/autoload.php';
+
+$openstack = new OpenStack\OpenStack([
+    'authUrl' => '{authUrl}',
+    'region'  => '{region}',
+    'user'    => [
+        'id'       => '{userId}',
+        'password' => '{password}',
+    ],
+]);
+
+$service = $openstack->blockStorageV2();
diff --git a/samples/BlockStorage/v3/create_with_region.php b/samples/BlockStorage/v3/create_with_region.php
@@ -0,0 +1,13 @@
+<?php
+
+require 'vendor/autoload.php';
+
+$openstack = new OpenStack\OpenStack([
+    'authUrl' => '{authUrl}',
+    'user'    => [
+        'id'       => '{userId}',
+        'password' => '{password}'
+    ],
+]);
+
+$identity = $openstack->identityV3(['region' => '{region}']);
diff --git a/samples/BlockStorage/v3/volume_types/create.php b/samples/BlockStorage/v3/volume_types/create.php
@@ -5,8 +5,10 @@
 $openstack = new OpenStack\OpenStack([
     'authUrl' => '{authUrl}',
     'region'  => '{region}',
-    'user'    => ['id' => '{userId}', 'password' => '{password}'],
-    'scope'   => ['project' => ['id' => '{projectId}']]
+    'user'    => [
+        'id'       => '{userId}',
+        'password' => '{password}']
+    ,
 ]);
 
 $service = $openstack->blockStorageV3();

diff --git a/samples/BlockStorage/v3/volume_types/delete.php b/samples/BlockStorage/v3/volume_types/delete.php
@@ -5,8 +5,10 @@
 $openstack = new OpenStack\OpenStack([
     'authUrl' => '{authUrl}',
     'region'  => '{region}',
-    'user'    => ['id' => '{userId}', 'password' => '{password}'],
-    'scope'   => ['project' => ['id' => '{projectId}']]
+    'user'    => [
+        'id'       => '{userId}',
+        'password' => '{password}']
+    ,
 ]);
 
 $service = $openstack->blockStorageV3();

diff --git a/samples/BlockStorage/v3/volume_types/list.php b/samples/BlockStorage/v3/volume_types/list.php
@@ -5,8 +5,10 @@
 $openstack = new OpenStack\OpenStack([
     'authUrl' => '{authUrl}',
     'region'  => '{region}',
-    'user'    => ['id' => '{userId}', 'password' => '{password}'],
-    'scope'   => ['project' => ['id' => '{projectId}']]
+    'user'    => [
+        'id'       => '{userId}',
+        'password' => '{password}']
+    ,
 ]);
 
 $service = $openstack->blockStorageV3();