From fa2bcd98a4db6f5446ad2b14698d18920a537179 Mon Sep 17 00:00:00 2001 From: Konstantin Babushkin Date: Sat, 20 Jan 2024 15:23:43 +0100 Subject: [PATCH] unify create-service docs --- doc/common/create-service.rst | 18 ++++++++++++++++++ doc/conf.py | 1 + doc/requirements.txt | 3 ++- doc/services/block-storage/v2/index.rst | 2 +- doc/services/block-storage/v3/create.rst | 13 ++----------- doc/services/compute/v2/images.rst | 2 +- doc/services/compute/v2/servers.rst | 2 +- doc/services/identity/v3/create.rst | 13 ++----------- doc/services/images/v2/create.rst | 13 ++----------- samples/BlockStorage/v3/create.php | 14 -------------- samples/BlockStorage/v3/create_with_region.php | 13 ------------- samples/Compute/v2/create.php | 14 -------------- samples/Compute/v2/create_with_region.php | 13 ------------- samples/Identity/v3/create.php | 14 -------------- samples/Identity/v3/create_with_region.php | 13 ------------- 15 files changed, 30 insertions(+), 118 deletions(-) create mode 100644 doc/common/create-service.rst delete mode 100644 samples/BlockStorage/v3/create.php delete mode 100644 samples/BlockStorage/v3/create_with_region.php delete mode 100644 samples/Compute/v2/create.php delete mode 100644 samples/Compute/v2/create_with_region.php delete mode 100644 samples/Identity/v3/create.php delete mode 100644 samples/Identity/v3/create_with_region.php diff --git a/doc/common/create-service.rst b/doc/common/create-service.rst new file mode 100644 index 00000000..799043dd --- /dev/null +++ b/doc/common/create-service.rst @@ -0,0 +1,18 @@ +Create Service +============== + +In order to work with the service you have to :doc:`setup the client ` first. + +Service can be created via :substitution-code:`|method|()` method of the ``OpenStack`` object. + +.. code-block:: php + :substitutions: + + $service = $openstack->|method|(); + +A list of additional options can be passed to the method. For example, to change the region: + +.. code-block:: php + :substitutions: + + $service = $openstack->|method|(['region' => '{region}']); diff --git a/doc/conf.py b/doc/conf.py index c5ad539a..14803257 100755 --- a/doc/conf.py +++ b/doc/conf.py @@ -31,6 +31,7 @@ 'sphinx.ext.autosummary', 'sphinxcontrib.phpdomain', 'sphinx_toolbox.collapse', + 'sphinx_substitution_extensions', ] source_suffix = '.rst' master_doc = 'index' diff --git a/doc/requirements.txt b/doc/requirements.txt index 76b768dc..505737dd 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,3 +1,4 @@ sphinxcontrib-phpdomain>=0.11.0 sphinx-rtd-theme>=0.5.1 -sphinx-toolbox>=3.5.0 \ No newline at end of file +sphinx-toolbox>=3.5.0 +sphinx-substitution-extensions \ No newline at end of file diff --git a/doc/services/block-storage/v2/index.rst b/doc/services/block-storage/v2/index.rst index 602969ab..e67c6a42 100644 --- a/doc/services/block-storage/v2/index.rst +++ b/doc/services/block-storage/v2/index.rst @@ -3,7 +3,7 @@ Block Storage v2 Block Storage v2 API is deprecated since Pike release and was removed in the Xena release. It is recommended to use Block Storage v3 API instead. However most of endpoints are identical, so if you still need -to use Block Storage v2 API, you can use the change `$openstack->blockStorageV3()` to `$openstack->blockStorageV2()` in examples. +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.php diff --git a/doc/services/block-storage/v3/create.rst b/doc/services/block-storage/v3/create.rst index 288b0371..80998dcc 100644 --- a/doc/services/block-storage/v3/create.rst +++ b/doc/services/block-storage/v3/create.rst @@ -1,12 +1,3 @@ -Create Service -============== +.. |method| replace:: blockStorageV3 -In order to work with the service you have to :doc:`setup the client ` 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 +.. include:: /common/create-service.rst \ No newline at end of file diff --git a/doc/services/compute/v2/images.rst b/doc/services/compute/v2/images.rst index 519884d3..9ca8e4b7 100644 --- a/doc/services/compute/v2/images.rst +++ b/doc/services/compute/v2/images.rst @@ -2,7 +2,7 @@ Images ====== .. warning:: - These APIs are proxy calls to the :doc:`/services/images/v2/`Image service. + These APIs are proxy calls to the :doc:`/services/images/v2/index` Image service. Nova has deprecated all the proxy APIs and users should use the native APIs instead. .. osdoc:: https://docs.openstack.org/api-ref/compute/#images-deprecated diff --git a/doc/services/compute/v2/servers.rst b/doc/services/compute/v2/servers.rst index a4f27d09..4865771d 100644 --- a/doc/services/compute/v2/servers.rst +++ b/doc/services/compute/v2/servers.rst @@ -149,7 +149,7 @@ Update The first step when updating a server is modifying the attributes you want updated. By default, only a server's name, IPv4 and IPv6 IPs, and its auto disk config attributes can be edited. -.. sample:: Compute/v2/servers/update_server.php +.. sample:: Compute/v2/servers/update.php Delete --------------- diff --git a/doc/services/identity/v3/create.rst b/doc/services/identity/v3/create.rst index c32b7699..9f0c6d3a 100644 --- a/doc/services/identity/v3/create.rst +++ b/doc/services/identity/v3/create.rst @@ -1,12 +1,3 @@ -Create Service -============== +.. |method| replace:: identityV3 -In order to work with the service you have to :doc:`setup the client ` first. - -Service can be created via ``computeV2()`` method of the ``OpenStack`` object. - -.. sample:: Compute/v3/create.php - -A list of additional options can be passed to the method. For example, to change the region: - -.. sample:: Compute/v3/create_with_region.php +.. include:: /common/create-service.rst diff --git a/doc/services/images/v2/create.rst b/doc/services/images/v2/create.rst index 43d3c0b5..b5415107 100644 --- a/doc/services/images/v2/create.rst +++ b/doc/services/images/v2/create.rst @@ -1,12 +1,3 @@ -Create Service -============== +.. |method| replace:: imagesV2 -In order to work with the service you have to :doc:`setup the client ` first. - -Service can be created via ``imagesV2()`` method of the ``OpenStack`` object. - -.. sample:: Image/v2/create.php - -A list of additional options can be passed to the method. For example, to change the region: - -.. sample:: Image/v2/create_with_region.php +.. include:: /common/create-service.rst diff --git a/samples/BlockStorage/v3/create.php b/samples/BlockStorage/v3/create.php deleted file mode 100644 index c2cde0e1..00000000 --- a/samples/BlockStorage/v3/create.php +++ /dev/null @@ -1,14 +0,0 @@ - '{authUrl}', - 'region' => '{region}', - 'user' => [ - 'id' => '{userId}', - 'password' => '{password}', - ], -]); - -$service = $openstack->blockStorageV3(); diff --git a/samples/BlockStorage/v3/create_with_region.php b/samples/BlockStorage/v3/create_with_region.php deleted file mode 100644 index ff100cf0..00000000 --- a/samples/BlockStorage/v3/create_with_region.php +++ /dev/null @@ -1,13 +0,0 @@ - '{authUrl}', - 'user' => [ - 'id' => '{userId}', - 'password' => '{password}' - ], -]); - -$identity = $openstack->blockStorageV3(['region' => '{region}']); \ No newline at end of file diff --git a/samples/Compute/v2/create.php b/samples/Compute/v2/create.php deleted file mode 100644 index 0fe40101..00000000 --- a/samples/Compute/v2/create.php +++ /dev/null @@ -1,14 +0,0 @@ - '{authUrl}', - 'region' => '{region}', - 'user' => [ - 'id' => '{userId}', - 'password' => '{password}', - ], -]); - -$compute = $openstack->computeV2(); diff --git a/samples/Compute/v2/create_with_region.php b/samples/Compute/v2/create_with_region.php deleted file mode 100644 index 48a1c184..00000000 --- a/samples/Compute/v2/create_with_region.php +++ /dev/null @@ -1,13 +0,0 @@ - '{authUrl}', - 'user' => [ - 'id' => '{userId}', - 'password' => '{password}' - ], -]); - -$compute = $openstack->computeV2(['region' => '{region}']); \ No newline at end of file diff --git a/samples/Identity/v3/create.php b/samples/Identity/v3/create.php deleted file mode 100644 index 276938ab..00000000 --- a/samples/Identity/v3/create.php +++ /dev/null @@ -1,14 +0,0 @@ - '{authUrl}', - 'region' => '{region}', - 'user' => [ - 'id' => '{userId}', - 'password' => '{password}' - ], -]); - -$identity = $openstack->identityV3(); \ No newline at end of file diff --git a/samples/Identity/v3/create_with_region.php b/samples/Identity/v3/create_with_region.php deleted file mode 100644 index e51fa957..00000000 --- a/samples/Identity/v3/create_with_region.php +++ /dev/null @@ -1,13 +0,0 @@ - '{authUrl}', - 'user' => [ - 'id' => '{userId}', - 'password' => '{password}' - ], -]); - -$identity = $openstack->identityV3(['region' => '{region}']); \ No newline at end of file