Merge user and users sections of the docs

The openstack doc standard location is 'user', so go with that.
Incorporate pages from the shade and occ docs into the appropriate
places in the user index file.

This still leaves user/logging and user/guide/logging which need to be
rationalized. That will come in the next commit, as it also needs to
actually rationalize the logging helper functions.

Remove the Makefile, as it's not used by things.

Change-Id: I26f36370ef9651f4bcaa7dee3b903309463d9592
This commit is contained in:
Monty Taylor 2018-01-10 09:10:40 -06:00
parent 26732e8374
commit 40d425c595
No known key found for this signature in database
GPG Key ID: 7BAE94BC7141A594
210 changed files with 469 additions and 415 deletions

View File

@ -1,136 +0,0 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
.PHONY: help clean html pdf dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " pdf to make pdf with rst2pdf"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
-rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
pdf:
$(SPHINXBUILD) -b pdf $(ALLSPHINXOPTS) $(BUILDDIR)/pdf
@echo
@echo "Build finished. The PDFs are in $(BUILDDIR)/pdf."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/NebulaDocs.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/NebulaDocs.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/NebulaDocs"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/NebulaDocs"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
make -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."

View File

@ -1,10 +1,21 @@
Welcome to the OpenStack SDK!
=============================
This documentation is split into two sections: one for
:doc:`users <users/index>` looking to build applications which make use of
OpenStack, and another for those looking to
:doc:`contribute <contributor/index>` to this project.
This documentation is split into three sections:
* an :doc:`installation <install/index>` guide
* a section for :doc:`users <user/index>` looking to build applications
which make use of OpenStack
* a section for those looking to :doc:`contribute <contributor/index>`
to this project
Installation
------------
.. toctree::
:maxdepth: 2
install/index
For Users
---------
@ -12,12 +23,8 @@ For Users
.. toctree::
:maxdepth: 2
users/index
install/index
user/index
.. TODO(shade) merge users/index and user/index into user/index
For Contributors
----------------

1
doc/source/user/examples Symbolic link
View File

@ -0,0 +1 @@
../../../examples

View File

@ -1,13 +0,0 @@
import openstack.cloud
# Initialize and turn on debug logging
openstack.cloud.simple_logging(debug=True)
for cloud_name, region_name in [
('my-vexxhost', 'ca-ymq-1'),
('my-citycloud', 'Buf1'),
('my-internap', 'ams01')]:
# Initialize cloud
cloud = openstack.openstack_cloud(cloud=cloud_name, region_name=region_name)
for server in cloud.search_servers('my-server'):
cloud.delete_server(server, wait=True, delete_ips=True)

View File

@ -1,6 +0,0 @@
import openstack.cloud
openstack.cloud.simple_logging(debug=True)
cloud = openstack.openstack_cloud(
cloud='my-vexxhost', region_name='ca-ymq-1')
cloud.get_image('Ubuntu 16.04.1 LTS [2017-03-03]')

View File

@ -1,7 +0,0 @@
import openstack.cloud
openstack.cloud.simple_logging()
cloud = openstack.openstack_cloud(cloud='fuga', region_name='cystack')
cloud.pprint([
image for image in cloud.list_images()
if 'ubuntu' in image.name.lower()])

View File

@ -1,6 +0,0 @@
import openstack.cloud
openstack.cloud.simple_logging(http_debug=True)
cloud = openstack.openstack_cloud(
cloud='my-vexxhost', region_name='ca-ymq-1')
cloud.get_image('Ubuntu 16.04.1 LTS [2017-03-03]')

View File

@ -1,7 +0,0 @@
import openstack.cloud
openstack.cloud.simple_logging(debug=True)
cloud = openstack.openstack_cloud(cloud='ovh', region_name='SBG1')
image = cloud.get_image('Ubuntu 16.10')
print(image.name)
print(image['name'])

View File

@ -1,7 +0,0 @@
import openstack.cloud
openstack.cloud.simple_logging()
cloud = openstack.openstack_cloud(cloud='fuga', region_name='cystack')
image = cloud.get_image(
'Ubuntu 16.04 LTS - Xenial Xerus - 64-bit - Fuga Cloud Based Image')
cloud.pprint(image)

View File

@ -1,5 +0,0 @@
import openstack.cloud
openstack.cloud.simple_logging(debug=True)
cloud = openstack.openstack_cloud(cloud='rax', region_name='DFW')
print(cloud.has_service('network'))

View File

@ -1,6 +0,0 @@
import openstack.cloud
openstack.cloud.simple_logging(debug=True)
cloud = openstack.openstack_cloud(cloud='kiss', region_name='region1')
print(cloud.has_service('network'))
print(cloud.has_service('container-orchestration'))

View File

@ -1,8 +0,0 @@
import openstack.cloud
openstack.cloud.simple_logging()
cloud = openstack.openstack_cloud(
cloud='fuga', region_name='cystack', strict=True)
image = cloud.get_image(
'Ubuntu 16.04 LTS - Xenial Xerus - 64-bit - Fuga Cloud Based Image')
cloud.pprint(image)

View File

@ -1,10 +0,0 @@
import openstack.cloud
openstack.cloud.simple_logging(debug=True)
cloud = openstack.openstack_cloud(cloud='ovh', region_name='SBG1')
cloud.create_object(
container='my-container', name='my-object',
filename='/home/mordred/briarcliff.sh3d',
segment_size=1000000)
cloud.delete_object('my-container', 'my-object')
cloud.delete_container('my-container')

View File

@ -1,10 +0,0 @@
import openstack.cloud
openstack.cloud.simple_logging(debug=True)
cloud = openstack.openstack_cloud(cloud='ovh', region_name='SBG1')
cloud.create_object(
container='my-container', name='my-object',
filename='/home/mordred/briarcliff.sh3d',
segment_size=1000000)
cloud.delete_object('my-container', 'my-object')
cloud.delete_container('my-container')

View File

@ -1,6 +0,0 @@
import openstack.cloud
openstack.cloud.simple_logging(http_debug=True)
cloud = openstack.openstack_cloud(
cloud='datacentred', app_name='AmazingApp', app_version='1.0')
cloud.list_networks()

View File

@ -1,15 +1,155 @@
==================
Shade User Guide
==================
Getting started with the OpenStack SDK
======================================
For a listing of terms used throughout the SDK, including the names of
projects and services supported by it, see the :doc:`glossary <../glossary>`.
Installation
------------
The OpenStack SDK is available on
`PyPI <https://pypi.python.org/pypi/openstacksdk>`_ under the name
**openstacksdk**. To install it, use ``pip``::
$ pip install openstacksdk
.. _user_guides:
User Guides
-----------
These guides walk you through how to make use of the libraries we provide
to work with each OpenStack service. If you're looking for a cookbook
approach, this is where you'll want to begin.
.. TODO(shade) Merge guides/logging and logging
.. toctree::
:maxdepth: 2
:maxdepth: 1
Configuration <config/index>
Connect to an OpenStack Cloud <guides/connect>
Connect to an OpenStack Cloud Using a Config File <guides/connect_from_config>
Using Cloud Abstration Layer <usage>
Logging <guides/logging>
Shade Logging <logging>
Microversions <microversions>
Baremetal <guides/baremetal>
Block Storage <guides/block_storage>
Clustering <guides/clustering>
Compute <guides/compute>
Database <guides/database>
Identity <guides/identity>
Image <guides/image>
Key Manager <guides/key_manager>
Message <guides/message>
Meter <guides/meter>
Network <guides/network>
Object Store <guides/object_store>
Orchestration <guides/orchestration>
API Documentation
-----------------
Service APIs are exposed through a two-layered approach. The classes
exposed through our *Connection* interface are the place to start if you're
an application developer consuming an OpenStack cloud. The *Resource*
interface is the layer upon which the *Connection* is built, with
*Connection* methods accepting and returning *Resource* objects.
The Cloud Abstraction layer has a data model.
.. toctree::
:maxdepth: 1
config/index
usage
logging
model
microversions
Connection Interface
********************
A *Connection* instance maintains your cloud config, session and authentication
information providing you with a set of higher-level interfaces to work with
OpenStack services.
.. toctree::
:maxdepth: 1
connection
Once you have a *Connection* instance, the following services may be exposed
to you. The combination of your ``CloudRegion`` and the catalog of the cloud
in question control which services are exposed, but listed below are the ones
provided by the SDK.
.. toctree::
:maxdepth: 1
Baremetal <proxies/baremetal>
Block Storage <proxies/block_storage>
Clustering <proxies/clustering>
Compute <proxies/compute>
Database <proxies/database>
Identity v2 <proxies/identity_v2>
Identity v3 <proxies/identity_v3>
Image v1 <proxies/image_v1>
Image v2 <proxies/image_v2>
Key Manager <proxies/key_manager>
Load Balancer <proxies/load_balancer_v2>
Message v1 <proxies/message_v1>
Message v2 <proxies/message_v2>
Network <proxies/network>
Meter <proxies/meter>
Metric <proxies/metric>
Object Store <proxies/object_store>
Orchestration <proxies/orchestration>
Workflow <proxies/workflow>
Resource Interface
******************
The *Resource* layer is a lower-level interface to communicate with OpenStack
services. While the classes exposed by the *Connection* build a convenience
layer on top of this, *Resources* can be used directly. However, the most
common usage of this layer is in receiving an object from a class in the
*Connection* layer, modifying it, and sending it back into the *Connection*
layer, such as to update a resource on the server.
The following services have exposed *Resource* classes.
.. toctree::
:maxdepth: 1
Baremetal <resources/baremetal/index>
Block Storage <resources/block_storage/index>
Clustering <resources/clustering/index>
Compute <resources/compute/index>
Database <resources/database/index>
Identity <resources/identity/index>
Image <resources/image/index>
Key Management <resources/key_manager/index>
Load Balancer <resources/load_balancer/index>
Meter <resources/meter/index>
Metric <resources/metric/index>
Network <resources/network/index>
Orchestration <resources/orchestration/index>
Object Store <resources/object_store/index>
Workflow <resources/workflow/index>
Low-Level Classes
*****************
The following classes are not commonly used by application developers,
but are used to construct applications to talk to OpenStack APIs. Typically
these parts are managed through the `Connection Interface`_, but their use
can be customized.
.. toctree::
:maxdepth: 1
resource
resource2
service_filter
utils
Presentations
=============

View File

@ -1,7 +1,7 @@
Baremetal API
==============
For details on how to use baremetal, see :doc:`/users/guides/baremetal`
For details on how to use baremetal, see :doc:`/user/guides/baremetal`
.. automodule:: openstack.baremetal.v1._proxy

View File

@ -1,7 +1,7 @@
Block Storage API
=================
For details on how to use block_storage, see :doc:`/users/guides/block_storage`
For details on how to use block_storage, see :doc:`/user/guides/block_storage`
.. automodule:: openstack.block_storage.v2._proxy

View File

@ -1,7 +1,7 @@
Compute API
===========
For details on how to use compute, see :doc:`/users/guides/compute`
For details on how to use compute, see :doc:`/user/guides/compute`
.. automodule:: openstack.compute.v2._proxy

View File

@ -1,7 +1,7 @@
Database API
============
For details on how to use database, see :doc:`/users/guides/database`
For details on how to use database, see :doc:`/user/guides/database`
.. automodule:: openstack.database.v1._proxy

View File

@ -1,7 +1,7 @@
Identity API v2
===============
For details on how to use identity, see :doc:`/users/guides/identity`
For details on how to use identity, see :doc:`/user/guides/identity`
.. automodule:: openstack.identity.v2._proxy

View File

@ -1,7 +1,7 @@
Identity API v3
===============
For details on how to use identity, see :doc:`/users/guides/identity`
For details on how to use identity, see :doc:`/user/guides/identity`
.. automodule:: openstack.identity.v3._proxy

View File

@ -1,7 +1,7 @@
Image API v1
============
For details on how to use image, see :doc:`/users/guides/image`
For details on how to use image, see :doc:`/user/guides/image`
.. automodule:: openstack.image.v1._proxy

View File

@ -1,7 +1,7 @@
Image API v2
============
For details on how to use image, see :doc:`/users/guides/image`
For details on how to use image, see :doc:`/user/guides/image`
.. automodule:: openstack.image.v2._proxy

View File

@ -2,7 +2,7 @@ KeyManager API
==============
For details on how to use key_management, see
:doc:`/users/guides/key_manager`
:doc:`/user/guides/key_manager`
.. automodule:: openstack.key_manager.v1._proxy

View File

@ -1,7 +1,7 @@
Message API v1
==============
For details on how to use message, see :doc:`/users/guides/message`
For details on how to use message, see :doc:`/user/guides/message`
.. automodule:: openstack.message.v1._proxy

View File

@ -1,7 +1,7 @@
Message API v2
==============
For details on how to use message, see :doc:`/users/guides/message`
For details on how to use message, see :doc:`/user/guides/message`
.. automodule:: openstack.message.v2._proxy

View File

@ -4,7 +4,7 @@ Meter API
.. caution::
BETA: This API is a work in progress and is subject to change.
For details on how to use meter, see :doc:`/users/guides/meter`
For details on how to use meter, see :doc:`/user/guides/meter`
.. automodule:: openstack.meter.v2._proxy

View File

@ -1,7 +1,7 @@
Network API
===========
For details on how to use network, see :doc:`/users/guides/network`
For details on how to use network, see :doc:`/user/guides/network`
.. automodule:: openstack.network.v2._proxy

View File

@ -1,7 +1,7 @@
Object Store API
================
For details on how to use this API, see :doc:`/users/guides/object_store`
For details on how to use this API, see :doc:`/user/guides/object_store`
.. automodule:: openstack.object_store.v1._proxy

View File

@ -1,7 +1,7 @@
Orchestration API
=================
For details on how to use orchestration, see :doc:`/users/guides/orchestration`
For details on how to use orchestration, see :doc:`/user/guides/orchestration`
.. automodule:: openstack.orchestration.v1._proxy

Some files were not shown because too many files have changed in this diff Show More