unify create-service docs

php-opencloud · Jan 20, 2024 · fa2bcd9 · fa2bcd9
1 parent d22523e
commit fa2bcd9
Show file tree

Hide file tree

Showing 15 changed files with 30 additions and 118 deletions.
diff --git a/doc/common/create-service.rst 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 </setup>` 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
@@ -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
@@ -1,3 +1,4 @@
 sphinxcontrib-phpdomain>=0.11.0
 sphinx-rtd-theme>=0.5.1
-sphinx-toolbox>=3.5.0
+sphinx-toolbox>=3.5.0
+sphinx-substitution-extensions
diff --git 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
@@ -1,12 +1,3 @@
-Create Service
-==============
+.. |method| replace:: blockStorageV3
 
-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
+.. include:: /common/create-service.rst
diff --git 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
@@ -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
@@ -1,12 +1,3 @@
-Create Service
-==============
+.. |method| replace:: identityV3
 
-In order to work with the service you have to :doc:`setup the client </setup>` 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
@@ -1,12 +1,3 @@
-Create Service
-==============
+.. |method| replace:: imagesV2
 
-In order to work with the service you have to :doc:`setup the client </setup>` 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
diff --git a/samples/BlockStorage/v3/create_with_region.php b/samples/BlockStorage/v3/create_with_region.php
diff --git a/samples/Compute/v2/create.php b/samples/Compute/v2/create.php
diff --git a/samples/Compute/v2/create_with_region.php b/samples/Compute/v2/create_with_region.php
diff --git a/samples/Identity/v3/create.php b/samples/Identity/v3/create.php
diff --git a/samples/Identity/v3/create_with_region.php b/samples/Identity/v3/create_with_region.php