diff --git a/doc/source/conf.py b/doc/source/conf.py index 61e9cab..03501b5 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -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'] diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst deleted file mode 100644 index 1728a61..0000000 --- a/doc/source/contributing.rst +++ /dev/null @@ -1,4 +0,0 @@ -============ -Contributing -============ -.. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst new file mode 100644 index 0000000..0b56da5 --- /dev/null +++ b/doc/source/contributor/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 + diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 0000000..7cfea0a --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,8 @@ +============================================ +python-moganclient Contributor Documentation +============================================ + +.. toctree:: + + contributing + testing diff --git a/doc/source/contributor/testing.rst b/doc/source/contributor/testing.rst new file mode 100644 index 0000000..9f559b1 --- /dev/null +++ b/doc/source/contributor/testing.rst @@ -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. diff --git a/doc/source/index.rst b/doc/source/index.rst index 2ee28ef..b923c51 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 \ No newline at end of file diff --git a/doc/source/osc/index.rst b/doc/source/osc/index.rst new file mode 100644 index 0000000..16793e8 --- /dev/null +++ b/doc/source/osc/index.rst @@ -0,0 +1,7 @@ +===================================== +python-moganclient User Documentation +===================================== + +.. toctree:: + + osc_plugin_cli diff --git a/doc/source/osc/osc_plugin_cli.rst b/doc/source/osc/osc_plugin_cli.rst new file mode 100644 index 0000000..a65a3b3 --- /dev/null +++ b/doc/source/osc/osc_plugin_cli.rst @@ -0,0 +1,87 @@ +============================================= +OpenStack Client Command-Line Interface (CLI) +============================================= + +.. program:: openstack baremetalcompute +.. highlight:: bash + +Synopsis +======== + +:program:`openstack [options] baremetalcompute` [command-options] + +:program:`openstack help baremetalcompute` + + +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 + + +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 --image --nic net-id= 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 diff --git a/doc/source/osc/v1/index.rst b/doc/source/osc/v1/index.rst new file mode 100644 index 0000000..ee45f5c --- /dev/null +++ b/doc/source/osc/v1/index.rst @@ -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 * diff --git a/doc/source/readme.rst b/doc/source/readme.rst deleted file mode 100644 index a6210d3..0000000 --- a/doc/source/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../README.rst diff --git a/doc/source/usage.rst b/doc/source/usage.rst deleted file mode 100644 index f1eeb0a..0000000 --- a/doc/source/usage.rst +++ /dev/null @@ -1,7 +0,0 @@ -===== -Usage -===== - -To use python-moganclient in a project:: - - import moganclient