x/python-moganclient
Code Issues Proposed changes

Improve moganclient documentation

Browse Source 
* Reorganize the structure of client documentation
* Add commands descriptions
* Add contributor guide docs

Change-Id: Ibd4cd2a98e574c3c7606d0bc450de94d48e518e7
This commit is contained in:
liusheng 2017-09-06 10:41:44 +08:00
parent 00b81835b5
commit 26880fc707
11 changed files with 322 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
doc/source/conf.py
View File

@ -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']

4
doc/source/contributing.rst
View File

@ -1,4 +0,0 @@
============
Contributing
============
.. include:: ../../CONTRIBUTING.rst

62
doc/source/contributor/contributing.rst Normal file
View File

@ -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

8
doc/source/contributor/index.rst Normal file
View File

@ -0,0 +1,8 @@
============================================
python-moganclient Contributor Documentation
============================================
.. toctree::
contributing
testing

32
doc/source/contributor/testing.rst Normal file
View File

@ -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.

21
doc/source/index.rst
View File

@ -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

7
doc/source/osc/index.rst Normal file
View File

@ -0,0 +1,7 @@
=====================================
python-moganclient User Documentation
=====================================
.. toctree::
osc_plugin_cli

87
doc/source/osc/osc_plugin_cli.rst Normal file
View File

@ -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

103
doc/source/osc/v1/index.rst Normal file
View File

@ -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
doc/source/readme.rst
View File

@ -1 +0,0 @@
.. include:: ../../README.rst

7
doc/source/usage.rst
View File

@ -1,7 +0,0 @@
=====
Usage
=====
To use python-moganclient in a project::
import moganclient