Improve moganclient documentation
* Reorganize the structure of client documentation * Add commands descriptions * Add contributor guide docs Change-Id: Ibd4cd2a98e574c3c7606d0bc450de94d48e518e7
This commit is contained in:
liusheng
parent
00b81835b5
commit
26880fc707
|
|
@ -24,8 +24,10 @@ sys.path.insert(0, os.path.abspath('../..'))
|
|||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
||||
extensions = [
|
||||
'sphinx.ext.autodoc',
|
||||
'sphinx.ext.viewcode',
|
||||
#'sphinx.ext.intersphinx',
|
||||
'openstackdocstheme'
|
||||
'openstackdocstheme',
|
||||
'cliff.sphinxext',
|
||||
]
|
||||
|
||||
# openstackdocstheme options
|
||||
|
|
@ -47,6 +49,8 @@ master_doc = 'index'
|
|||
project = u'python-moganclient'
|
||||
copyright = u'2016, OpenStack Foundation'
|
||||
|
||||
modindex_common_prefix = ['moganclient.']
|
||||
|
||||
# If true, '()' will be appended to :func: etc. cross-reference text.
|
||||
add_function_parentheses = True
|
||||
|
||||
|
|
@ -64,6 +68,7 @@ pygments_style = 'sphinx'
|
|||
# html_theme_path = ["."]
|
||||
# html_theme = '_theme'
|
||||
# html_static_path = ['static']
|
||||
html_theme = 'openstackdocs'
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = '%sdoc' % project
|
||||
|
|
@ -82,3 +87,9 @@ latex_documents = [
|
|||
|
||||
# Example configuration for intersphinx: refer to the Python standard library.
|
||||
#intersphinx_mapping = {'http://docs.python.org/': None}
|
||||
|
||||
autoprogram_cliff_application = 'openstack'
|
||||
|
||||
autoprogram_cliff_ignored = [
|
||||
'--help', '--format', '--column', '--max-width', '--fit-width',
|
||||
'--print-empty', '--prefix', '--noindent', '--quote']
|
||||
|
|
|
|||
|
|
@ -1,4 +0,0 @@
|
|||
============
|
||||
Contributing
|
||||
============
|
||||
.. include:: ../../CONTRIBUTING.rst
|
||||
|
|
@ -0,0 +1,62 @@
|
|||
.. _contributing:
|
||||
|
||||
==================================
|
||||
Contributing to python-moganclient
|
||||
==================================
|
||||
|
||||
If you're interested in contributing to the python-moganclient project,
|
||||
the following will help get you started.
|
||||
|
||||
#openstack-mogan on Freenode IRC Network
|
||||
----------------------------------------
|
||||
There is a very active chat channel at irc://freenode.net/#openstack-mogan.
|
||||
This is usually the best place to ask questions and find your way around.
|
||||
IRC stands for Internet Relay Chat and it is a way to chat online in real
|
||||
time. You can ask a question and come back later to read the answer in the
|
||||
log files. Logs for the #openstack-mogan IRC channel are stored at
|
||||
http://eavesdrop.openstack.org/irclogs/%23openstack-mogan/.
|
||||
|
||||
Contributor License Agreement
|
||||
-----------------------------
|
||||
|
||||
.. index::
|
||||
single: license; agreement
|
||||
|
||||
In order to contribute to the python-moganclient project, you need to have
|
||||
signed OpenStack's contributor's agreement.
|
||||
|
||||
.. seealso::
|
||||
|
||||
* https://docs.openstack.org/infra/manual/developers.html
|
||||
* https://wiki.openstack.org/wiki/CLA
|
||||
|
||||
LaunchPad Project
|
||||
-----------------
|
||||
|
||||
Most of the tools used for OpenStack depend on a launchpad.net ID for
|
||||
authentication. After signing up for a launchpad account, join the
|
||||
"openstack" team to have access to the mailing list and receive
|
||||
notifications of important events.
|
||||
|
||||
.. seealso::
|
||||
|
||||
* https://launchpad.net
|
||||
* https://launchpad.net/python-moganclient
|
||||
* https://launchpad.net/~openstack
|
||||
|
||||
|
||||
Project Hosting Details
|
||||
-----------------------
|
||||
|
||||
Bug tracker
|
||||
https://launchpad.net/python-moganclient
|
||||
|
||||
Mailing list (prefix subjects with ``[mogan]`` for faster responses)
|
||||
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
|
||||
|
||||
Code Hosting
|
||||
https://git.openstack.org/cgit/openstack/python-moganclient
|
||||
|
||||
Code Review
|
||||
https://review.openstack.org/#/q/status:open+project:openstack/python-moganclient,n,z
|
||||
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
============================================
|
||||
python-moganclient Contributor Documentation
|
||||
============================================
|
||||
|
||||
.. toctree::
|
||||
|
||||
contributing
|
||||
testing
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
.. _testing:
|
||||
|
||||
=======
|
||||
Testing
|
||||
=======
|
||||
|
||||
Python Guideline Enforcement
|
||||
............................
|
||||
|
||||
All code has to pass the pep8 style guideline to merge into OpenStack, to
|
||||
validate the code against these guidelines you can run::
|
||||
|
||||
$ tox -e pep8
|
||||
|
||||
Unit Testing
|
||||
............
|
||||
|
||||
It is strongly encouraged to run the unit tests locally under one or more
|
||||
test environments prior to submitting a patch. To run all the recommended
|
||||
environments sequentially and pep8 style guideline run::
|
||||
|
||||
$ tox
|
||||
|
||||
You can also selectively pick specific test environments by listing your
|
||||
chosen environments after a -e flag::
|
||||
|
||||
$ tox -e py35,py27,pep8,pypy
|
||||
|
||||
.. note::
|
||||
Tox sets up virtual environment and installs all necessary dependencies.
|
||||
Sharing the environment with devstack testing is not recommended due to
|
||||
conflicting configuration with system dependencies.
|
||||
|
|
@ -1,25 +1,26 @@
|
|||
.. python-moganclient documentation master file, created by
|
||||
sphinx-quickstart on Tue Jul 9 22:26:36 2013.
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
==========================================
|
||||
Python Bindings to the OpenStack Mogan API
|
||||
==========================================
|
||||
|
||||
Welcome to python-moganclient's documentation!
|
||||
==============================================
|
||||
This is a client for OpenStack `Mogan`_ API. There's a Python API
|
||||
(the `moganclient` modules), and a set of event related commands
|
||||
which are integrated with the OSC CLI tool. Each implements the entire Mogan
|
||||
API.
|
||||
|
||||
Contents:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
readme
|
||||
installation
|
||||
usage
|
||||
contributing
|
||||
contributor/index
|
||||
osc/index
|
||||
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
|
||||
.. _Mogan: https://wiki.openstack.org/wiki/Mogan
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
=====================================
|
||||
python-moganclient User Documentation
|
||||
=====================================
|
||||
|
||||
.. toctree::
|
||||
|
||||
osc_plugin_cli
|
||||
|
|
@ -0,0 +1,87 @@
|
|||
=============================================
|
||||
OpenStack Client Command-Line Interface (CLI)
|
||||
=============================================
|
||||
|
||||
.. program:: openstack baremetalcompute
|
||||
.. highlight:: bash
|
||||
|
||||
Synopsis
|
||||
========
|
||||
|
||||
:program:`openstack [options] baremetalcompute` <command> [command-options]
|
||||
|
||||
:program:`openstack help baremetalcompute` <command>
|
||||
|
||||
|
||||
Description
|
||||
===========
|
||||
|
||||
The OpenStack Client plugin interacts with the Bare Metal service
|
||||
through the ``openstack baremetalcompute`` command line interface (CLI).
|
||||
|
||||
To use ``openstack`` CLI, the OpenStackClient should be installed::
|
||||
|
||||
# pip install python-openstackclient
|
||||
|
||||
To use the CLI, you must provide your OpenStack username, password,
|
||||
project, and auth endpoint. You can use configuration options
|
||||
``--os-username``, ``--os-password``, ``--os-project-id``
|
||||
(or ``--os-project-name``), and ``--os-auth-url``,
|
||||
or set the corresponding environment variables::
|
||||
|
||||
$ export OS_USERNAME=user
|
||||
$ export OS_PASSWORD=password
|
||||
$ export OS_PROJECT_NAME=project # or OS_PROJECT_ID
|
||||
$ export OS_PROJECT_DOMAIN_ID=default
|
||||
$ export OS_USER_DOMAIN_ID=default
|
||||
$ export OS_IDENTITY_API_VERSION=3
|
||||
$ export OS_AUTH_URL=http://auth.example.com:5000/identity
|
||||
|
||||
This CLI is provided by python-openstackclient and osc-lib projects:
|
||||
|
||||
* https://git.openstack.org/openstack/python-openstackclient
|
||||
* https://git.openstack.org/openstack/osc-lib
|
||||
|
||||
|
||||
Getting help
|
||||
============
|
||||
|
||||
To get a list of available (sub)commands and options, run::
|
||||
|
||||
$ openstack help baremetalcompute
|
||||
|
||||
To get usage and options of a command, run::
|
||||
|
||||
$ openstack help baremetalcompute <sub-command>
|
||||
|
||||
|
||||
Examples
|
||||
========
|
||||
|
||||
Get information about the openstack baremetalcompute server create command::
|
||||
|
||||
$ openstack help baremetalcompute server create
|
||||
|
||||
Get a list of baremetalcompute flavors::
|
||||
|
||||
$ openstack baremetalcompute flavor list
|
||||
|
||||
Boot a Bare metal server::
|
||||
|
||||
$ openstack baremetalcompute server create --flavor <FLAVOR> --image <IMAGE> --nic net-id=<NETWORK> test
|
||||
|
||||
Get a list of baremetal nodes aggregates::
|
||||
|
||||
$ openstack baremetalcompute aggregate list
|
||||
|
||||
Command Reference
|
||||
=================
|
||||
|
||||
List of released CLI commands available in openstack client. These commands
|
||||
can be referenced by doing ``openstack help baremetalcompute``.
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 2
|
||||
|
||||
v1/index
|
||||
|
|
@ -0,0 +1,103 @@
|
|||
|
||||
=======================
|
||||
Baremetalcompute server
|
||||
=======================
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute server create
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute server show
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute server list
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute server delete
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute server add floating ip
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute server add interface
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute server lock
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute server netinfo
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute server reboot
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute server remove floating ip
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute server remove interface
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute server set
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute server start
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute server stop
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute server unlock
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute server unset
|
||||
|
||||
=============================
|
||||
Baremetalcompute server group
|
||||
=============================
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute server group create
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute server group show
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute server group list
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute server group delete
|
||||
|
||||
=======================
|
||||
BaremetalCompute flavor
|
||||
=======================
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute flavor *
|
||||
|
||||
==========================
|
||||
BaremetalCompute aggregate
|
||||
==========================
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute aggregate *
|
||||
|
||||
========================
|
||||
BaremetalCompute keypair
|
||||
========================
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute keypair *
|
||||
|
||||
=====================
|
||||
BaremetalCompute node
|
||||
=====================
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute node *
|
||||
|
||||
==================================
|
||||
BaremetalCompute availability zone
|
||||
==================================
|
||||
|
||||
.. autoprogram-cliff:: openstack.baremetal_compute.v1
|
||||
:command: baremetalcompute availability zone *
|
||||
|
|
@ -1 +0,0 @@
|
|||
.. include:: ../../README.rst
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
=====
|
||||
Usage
|
||||
=====
|
||||
|
||||
To use python-moganclient in a project::
|
||||
|
||||
import moganclient
|
||||
Loading…
Reference in New Issue