Clarify docs (#389)

* Rewrite most of documentation. 
* Make creating the `$openstack` object more clear.
* Rename and rearrange main operations as CRUDL (Create, Read, Update, Delete, List)

doc/_exts/osdoc.py

@@ -0,0 +1,31 @@
+from docutils.parsers.rst import Directive
+from docutils import nodes
+
+
+class OsDoc(Directive):
+    required_arguments = 1
+    has_content = True
+
+    def run(self):
+        full_url = self.arguments[0]
+        title = 'official documentation'
+
+        text = []
+        text.extend([
+            nodes.Text('More information can be found in the '),
+            nodes.reference(title, title, internal=False, refuri=self.arguments[0]),
+            nodes.Text('.')
+        ])
+
+        return [nodes.paragraph(
+            '',
+            '',
+            nodes.Text('More information can be found in the '),
+            nodes.reference(title, title, internal=False, refuri=full_url),
+            nodes.Text('.')
+        )]
+
+
+def setup(app):
+    app.add_directive('osdoc', OsDoc)
+    return {'version': '0.1'}

doc/_exts/samples.py

@@ -1,33 +1,41 @@
 from docutils import nodes
-from sphinx.addnodes import download_reference
+from docutils.parsers.rst import directives
 from sphinx.directives.code import LiteralInclude
 import re
 
+from sphinx.util.typing import OptionSpec
+
+
 class Sample(LiteralInclude):
+    option_spec: OptionSpec = {
+        'full': directives.flag,
+    }
+
+    def run(self):
+        self.arguments[0] = "/../samples/" + self.arguments[0]
+        self.options['language'] = 'php'
 
-  def run(self):
-    self.arguments[0] = "/../samples/" + self.arguments[0]
-    self.options['language'] = 'php'
+        pattern = r"[\s+]?(\<\?php.*?]\);)"
 
-    pattern = r"[\s+]?(\<\?php.*?]\);)"
+        code_block = super(Sample, self).run()[0]
+        if 'full' in self.options:
+            return [code_block]
 
-    code_block = super(Sample, self).run()[0]
-    string = str(code_block[0])
+        string = str(code_block[0])
 
-    match = re.match(pattern, string, re.S)
-    if match is None:
-      return [code_block]
+        match = re.match(pattern, string, re.S)
+        if match is None:
+            return [code_block]
 
-    auth_str = match.group(1).strip()
-    main_str = re.sub(pattern, "", string, 0, re.S).strip()
+        main_str = re.sub(pattern, "", string, 0, re.S).strip()
+        if main_str == '':
+            return [code_block]
 
-    show_hide_btn = download_reference(reftarget=self.arguments[0])
+        return [
+            nodes.literal_block(main_str, main_str, language="php")
+        ]
 
-    return [
-        show_hide_btn, 
-        nodes.literal_block(auth_str, auth_str, language="php"), 
-        nodes.literal_block(main_str, main_str, language="php")]
 
 def setup(app):
-  app.add_directive('sample', Sample)
-  return {'version': '0.1'}
+    app.add_directive('sample', Sample)
+    return {'version': '0.1'}

doc/_static/css/custom.css

@@ -0,0 +1,4 @@
+summary {
+    margin-bottom: 1rem;
+    cursor: pointer;
+}

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}']);

doc/common/service.rst

@@ -0,0 +1 @@
+In order to work with |models| you have to :doc:`create the service <create>` first.

doc/conf.py

@@ -23,14 +23,23 @@
 lexers['php-annotations'] = PhpLexer(startinline=True, linenos=1)
 primary_domain = 'php'
 
-extensions = ['samples', 'refdoc', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinxcontrib.phpdomain']
+extensions = [
+    'samples',
+    'refdoc',
+    'osdoc',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinxcontrib.phpdomain',
+    'sphinx_toolbox.collapse',
+    'sphinx_substitution_extensions',
+]
 source_suffix = '.rst'
 master_doc = 'index'
 project = u'php-opencloud'
 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'
@@ -39,6 +48,13 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'php-openclouddoc'
 
+# These folders are copied to the documentation's HTML output
+html_static_path = ['_static']
+
+html_css_files = [
+    'css/custom.css',
+]
+
 latex_documents = [
   ('index', 'php-opencloud.tex', u'php-opencloud Documentation',
    u'Jamie Hannaford', 'manual'),

doc/index.rst

@@ -1,40 +1,23 @@
 Welcome to the OpenStack SDK for PHP!
 =====================================
 
-Requirements
-------------
-
-* PHP >= 7, < 9
-* cURL extension
-
-Installation
-------------
-
-You must install this library through Composer:
-
-.. code-block:: bash
+About
+-----
 
-    composer require php-opencloud/openstack
+OpenStack SDK allows PHP developers to easily connect to OpenStack APIs in a simple and idiomatic way.
+This binding is specifically designed for OpenStack APIs, but other provider SDKs are available.
+Multiple OpenStack services, and versions of services, are supported.
 
-If you do not have Composer installed, please read the `Composer installation instructions`_.
-
-Once you have installed the SDK as a dependency of your project, you will need to load Composer’s autoloader
-(which registers all the required namespaces). To do this, place the following line of PHP code at the top of your
-application’s PHP files:
-
-.. code-block:: php
-
-    require 'vendor/autoload.php';
-
-This assumes your application's PHP files are located in the same folder as ``vendor/``. If your files are located
-elsewhere, please supply the path to vendor/autoload.php in the require statement above.
+.. toctree::
+    install
+    setup
 
 Supported services
 ------------------
 
 .. toctree::
     :glob:
-    :maxdepth: 1
+    :maxdepth: 0
 
     services/**/index
 
@@ -49,6 +32,5 @@ Contributing
 If you'd like to contribute to the project, or require help running the unit/integration tests, please view the
 `contributing guidelines`_.
 
-.. _Composer installation instructions: `https://getcomposer.org/doc/00-intro.md`
-.. _Github repo: `https://github.com/php-opencloud/openstack`
-.. _contributing guidelines: `https://github.com/php-opencloud/openstack/blob/master/CONTRIBUTING.md`
+.. _Github repo: https://github.com/php-opencloud/openstack
+.. _contributing guidelines: https://github.com/php-opencloud/openstack/blob/master/CONTRIBUTING.md

doc/install.rst

@@ -0,0 +1,35 @@
+Installation
+============
+
+Requirements
+------------
+
+* PHP >= 7, < 9
+* cURL extension
+
+Install via composer
+--------------------
+
+You must install this library through Composer:
+
+.. code-block:: bash
+
+    composer require php-opencloud/openstack
+
+If you do not have Composer installed, please read the `Composer installation instructions`_.
+
+Include autoloader
+------------------
+
+Once you have installed the SDK as a dependency of your project, you will need to load Composer’s autoloader
+(which registers all the required namespaces). To do this, place the following line of PHP code at the top of your
+application’s PHP files:
+
+.. code-block:: php
+
+    require 'vendor/autoload.php';
+
+This assumes your application's PHP files are located in the same folder as ``vendor/``. If your files are located
+elsewhere, please supply the path to vendor/autoload.php in the require statement above.
+
+.. _Composer installation instructions: https://getcomposer.org/doc/00-intro.md

doc/requirements.txt

@@ -1,2 +1,4 @@
 sphinxcontrib-phpdomain>=0.11.0
-sphinx-rtd-theme>=0.5.1
+sphinx-rtd-theme>=0.5.1
+sphinx-toolbox>=3.5.0
+sphinx-substitution-extensions

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_service.php
+.. sample:: BlockStorage/v2/create.php

doc/services/block-storage/v3/create.rst

@@ -0,0 +1,3 @@
+.. |method| replace:: blockStorageV3
+
+.. include:: /common/create-service.rst

doc/services/block-storage/v3/index.rst

@@ -1,9 +1,15 @@
 Block Storage v3
 ================
 
+OpenStack Block Storage API v3 (Cinder). Cinder is the OpenStack Block Storage service for providing volumes
+to Nova virtual machines, Ironic bare metal hosts, containers and more.
+
+.. osdoc:: https://docs.openstack.org/api-ref/block-storage/v3/
+
 .. toctree::
-   :maxdepth: 3
+    :maxdepth: 3
 
-   volumes
-   volume-types
-   snapshots
+    create
+    volumes
+    volume-types
+    snapshots

doc/services/block-storage/v3/snapshots.rst

@@ -1,18 +1,26 @@
 Snapshots
 =========
 
-List volumes
-------------
+A snapshot is 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: