add collapsible auth code

doc/_exts/samples.py

@@ -1,5 +1,6 @@
 from docutils import nodes
 from sphinx.directives.code import LiteralInclude
+from sphinx.util.nodes import make_refnode
 from sphinx_toolbox.collapse import CollapseNode
 import re
 
@@ -22,11 +23,26 @@ def run(self):
         auth_str = match.group(1).strip()
         main_str = re.sub(pattern, "", string, 0, re.S).strip()
 
+        env = self.state.document.settings.env
+        ref_node = make_refnode(
+            env.app.builder,
+            fromdocname=env.docname,
+            todocname='use',
+            targetid='',
+            child=nodes.Text('Use OpenStack library')
+        )
+
         return [
             CollapseNode(
-                "",
-                "show auth code",
-                nodes.literal_block("This is example", "This is example"),
+                '',
+                'show auth code',
+                nodes.paragraph(
+                    '',
+                    '',
+                    nodes.Text('Example of how to create OpenStack object. See '),
+                    ref_node,
+                    nodes.Text(' for all options.')
+                ),
                 nodes.literal_block(auth_str, auth_str, language="php")
             ),
             nodes.literal_block(main_str, main_str, language="php")

doc/index.rst

@@ -9,7 +9,8 @@ This binding is specifically designed for OpenStack APIs, but other provider SDK
 Multiple OpenStack services, and versions of services, are supported.
 
 .. toctree::
-    quick-start
+    install
+    use
 
 Supported services
 ------------------

doc/install.rst

@@ -0,0 +1,35 @@
+Quick Start
+===========
+
+Requirements
+------------
+
+* PHP >= 7, < 9
+* cURL extension
+
+Installation
+------------
+
+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 the 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/quick-start.rst → doc/use.rst

@@ -1,49 +1,17 @@
-Quick start
-===========
+Use OpenStack library
+=====================
 
-Requirements
-------------
-
-* PHP >= 7, < 9
-* cURL extension
-
-Installation
-------------
-
-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 the 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.
-
-Creating a client
------------------
-
-To create a client, you will need to provide the following information:
+In order to access services you have to create the client object. To do it, you will need to provide the
+following information:
 
 * The identity service URL (``authUrl``)
 * The region in which you want to operate (``region``)
 * The credentials of the user you want to authenticate: ``user``, ``tokenId``, ``cachedToken``
   or ``application_credential``
 
-Only the ``authUrl`` is mandatory to create a client. But you will have to provide the ``region`` and ``user``
-to each service you create. So it is recommended to provide them when creating the client.
+Only the ``authUrl`` is mandatory to create the client. But you will have to provide the ``region`` and user
+credentials to each service you create. So it is recommended to provide them when creating the client which
+would propagate these options to each service.
 
 There are different ways to provide the authentication credentials. See the :doc:`services/identity/v3/tokens`
 section for the full list of options. You should provide credentials to the `OpenStack` constructor as an array
@@ -92,5 +60,3 @@ You can specify the scope of the token:
             ],
         ],
     ]);
-
-.. _Composer installation instructions: https://getcomposer.org/doc/00-intro.md