doc-migration: new directory layout

This patch introduces a new directory layout
in doc/source in conformance with the OpenStack
manuals project migration spec [1], moves the
existing content in manila/doc/source into the
new directories, and adjusts index files accordingly.

This is the first step in the migration process
as outlined in the spec.

[1] https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html

Closes-Bug: #1706181
Change-Id: I8964d066bb838fabbe94239ac108bff884c6ff76
Depends-On: I72be6303f9be77c0461eaacbc61bad8372546fb5
Depends-On: Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454

doc/source/contributor/index.rst

@@ -0,0 +1,47 @@
+Contributing
+============
+
+Code is hosted at `git.openstack.org`_. Submit bugs to the
+python-manilaclient project on `Launchpad`_. Submit code to the
+openstack/python-manilaclient project using `Gerrit`_.
+
+.. _git.openstack.org: https://git.openstack.org/cgit/openstack/python-manilaclient
+.. _Launchpad: https://launchpad.net/python-manilaclient
+.. _Gerrit: https://docs.openstack.org/infra/manual/developers.html#development-workflow
+
+Testing
+-------
+
+Manilaclient has two types of tests - 'unit' and 'functional'.
+
+The preferred way to run tests is using ``tox``.
+
+See `Consistent Testing Interface`_ for more details.
+
+.. _Consistent Testing Interface: https://git.openstack.org/cgit/openstack/governance/tree/reference/project-testing-interface.rst
+
+Functional tests
+----------------
+
+Functional CLI tests require several things to be able to run:
+
+* Deployed and working manila service.
+* Configured config file.
+
+Config file is used to get information like 'auth_url', 'username',
+'tenant_name' and 'password'.
+To get config sample need to run following 'tox' job:
+
+.. code-block:: console
+
+  $ tox -e genconfig
+
+This will create file 'etc/manilaclient/manilaclient.conf.sample' with all
+available config opts.
+Then rename it removing ".sample" and set values for opts there. After it,
+tests can be run using following tox job:
+
+.. code-block:: console
+
+  $ tox -e functional
+

doc/source/exts/clidoc/__init__.py

@@ -30,7 +30,7 @@ def _get_cli_output():
 
 def builder_inited(app):
     # generate the missing rst files
-    with open(os.path.join(app.env.srcdir, "manila_cli_output.rst.inc"), "w") as f:
+    with open(os.path.join(app.env.srcdir, "cli/manila_cli_output.rst.inc"), "w") as f:
         f.write("``manila help``::\n\n")
         f.write("\n".join(_get_cli_output()))
         f.write("\n")

doc/source/index.rst

@@ -2,77 +2,39 @@ Python bindings to the OpenStack Manila API
 ===========================================
 
 This is a client for OpenStack Manila API. There's :doc:`a Python API
-<api>` (the :mod:`manilaclient` module), and a :doc:`command-line script
-<shell>` (installed as :program:`manila`). Each implements the entire
+<user/api>` (the :mod:`manilaclient` module), and a :doc:`command-line script
+<user/shell>` (installed as :program:`manila`). Each implements the entire
 OpenStack Manila API.
 
 You'll need credentials for an OpenStack cloud that implements the
 Manila API in order to use the manila client.
 
-Contents:
+Command-Line Reference
+======================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   shell
-   api
+   user/shell
+
+API
+===
+
+.. toctree::
+   :maxdepth: 1
+
+   user/api
 
 Contributing
 ============
 
-Code is hosted at `git.openstack.org`_. Submit bugs to the
-python-manilaclient project on `Launchpad`_. Submit code to the
-openstack/python-manilaclient project using `Gerrit`_.
+.. toctree::
+   :maxdepth: 1
 
-.. _git.openstack.org: https://git.openstack.org/cgit/openstack/python-manilaclient
-.. _Launchpad: https://launchpad.net/python-manilaclient
-.. _Gerrit: https://docs.openstack.org/infra/manual/developers.html#development-workflow
-
-Testing
--------
-
-Manilaclient has two types of tests - 'unit' and 'functional'.
-
-The preferred way to run tests is using ``tox``.
-
-See `Consistent Testing Interface`_ for more details.
-
-.. _Consistent Testing Interface: https://git.openstack.org/cgit/openstack/governance/tree/reference/project-testing-interface.rst
-
-Functional tests
-----------------
-
-Functional CLI tests require several things to be able to run:
-
-* Deployed and working manila service.
-* Configured config file.
-
-Config file is used to get information like 'auth_url', 'username',
-'tenant_name' and 'password'.
-To get config sample need to run following 'tox' job:
-
-.. code-block:: console
-
-  $ tox -e genconfig
-
-This will create file 'etc/manilaclient/manilaclient.conf.sample' with all
-available config opts.
-Then rename it removing ".sample" and set values for opts there. After it,
-tests can be run using following tox job:
-
-.. code-block:: console
-
-  $ tox -e functional
+   contributor/index
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
-
-
-Release Notes
-=============
-
-No releases.

doc/source/user/api.rst

@@ -1,5 +1,5 @@
-The :mod:`manilaclient` Python API
-==================================
+The :program:`manilaclient` Python API
+======================================
 
 .. module:: manilaclient
    :synopsis: A client for the OpenStack Manila API.
@@ -7,7 +7,7 @@ The :mod:`manilaclient` Python API
 .. currentmodule:: manilaclient
 
 Usage
-=====
+-----
 
 In order to use the Python API directly, you must first obtain an auth
 token and identify which endpoint you wish to speak to. Once you have

doc/source/user/shell.rst

@@ -38,7 +38,7 @@ For example, in Bash you'd use::
     export OS_PASSWORD=bar
     export OS_TENANT_NAME=foobarproject
     export OS_AUTH_URL=http://...
-    export OS_SHARE_API_VERSION=1
+    export OS_SHARE_API_VERSION=2
 
 From there, all shell commands take the form::
 
@@ -48,4 +48,4 @@ Run :program:`manila help` to get a full list of all possible commands,
 and run :program:`manila help <command>` to get detailed help for that
 command.
 
-.. include:: manila_cli_output.rst.inc
+.. include:: ../cli/manila_cli_output.rst.inc