From 074efe4ff803b05f7d931e3f38ad78aa319dea72 Mon Sep 17 00:00:00 2001 From: Konstantin Babushkin Date: Wed, 17 Jan 2024 23:02:21 +0100 Subject: [PATCH] add collapsible auth code --- doc/_exts/samples.py | 22 +++++++++++++-- doc/index.rst | 3 +- doc/install.rst | 35 +++++++++++++++++++++++ doc/{quick-start.rst => use.rst} | 48 +++++--------------------------- 4 files changed, 63 insertions(+), 45 deletions(-) create mode 100644 doc/install.rst rename doc/{quick-start.rst => use.rst} (55%) diff --git a/doc/_exts/samples.py b/doc/_exts/samples.py index 20c8504d..18eebb39 100644 --- a/doc/_exts/samples.py +++ b/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") diff --git a/doc/index.rst b/doc/index.rst index a8e1f236..58867d43 100644 --- a/doc/index.rst +++ b/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 ------------------ diff --git a/doc/install.rst b/doc/install.rst new file mode 100644 index 00000000..edca2d95 --- /dev/null +++ b/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 diff --git a/doc/quick-start.rst b/doc/use.rst similarity index 55% rename from doc/quick-start.rst rename to doc/use.rst index fbcad26a..491f2d73 100644 --- a/doc/quick-start.rst +++ b/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