Barbican/Documentation

= Barbican Documentation =

Installation Guides
These DocBook guides should be aimed at deployers of OpenStack clouds. They should probably cover installation for at least one production-ready configuration of Barbican. Currently the source for these guides is in the main Barbican repo, but it's only a place-holder. https://github.com/openstack/barbican/blob/master/docs/src/docbkx/ck-install.xml

Eventually, we should have have four installation guides: Debian, openSUSE, RHEL/CentOS, and Ubuntu.

The only documented installation is for an insecure development environment, which is documented in the GitHub wiki https://github.com/cloudkeep/barbican/wiki/Barbican-Quick-Start-Guide and is by no means a good substitute for these guides.

TODO: Figure out the best place to develop these during incubation

Eventually, the source for these guides should end up in http://github.com/openstack/openstack-manuals

Administration Guide
This DocBook guide should be aimed at operators of OpenStack clouds. It should cover common administration tasks for running Barbican. This guide has not yet been started.

TODO: Figure out the best place to develop these during incubation

Eventually, this guide should end up in http://github.com/openstack/openstack-manuals

Configuration Guide
This DocBook guide should be aimed at deployers of OpenStack clouds. It should thoroughly cover all deployment options for Barbican. This guide has not yet been started.

TODO: Figure out the best place to develop these during incubation

Eventually, this guide should end up in http://github.com/openstack/openstack-manuals

User Guide
This guide is aimed at users of the Barbican API. The source currently lives in the main Barbican repo https://github.com/openstack/barbican/blob/master/docs/src/docbkx/ck-devguide.xml

TODO: The API definition should be split up into its own repo

TODO: Figure out the best place to develop these during incubation

Eventually, this guide should end up in http://github.com/openstack/openstack-manuals

API Quick Start
This guide is aimed at new users of the Barbican API and should cover only a few use cases to get readers acquainted with the Barbican API. The source currently lives in the main Barbican repo https://github.com/openstack/barbican/blob/master/docs/src/docbkx/ck-gettingstarted.xml

TODO: Figure out the best place to develop these during incubation

Eventually, this quick start should end up in https://github.com/openstack/api-site

API Reference
The API Reference is currently in the CloudKeep Barbican Wiki, as well as the User Guide in the main Barbican Repo https://github.com/openstack/barbican/blob/master/docs/src/docbkx/ck-devguide.xml

TODO: Update Orders API

TODO: The GitHub wiki and the API section of the User Guide should be merged into a stand-alone api repository to be located at https://github.com/openstack/key-management-api (See https://github.com/openstack/identity-api for example)

Barbican
Barbican developer documentation is aimed at developer contributors. They're published to: http://docs.openstack.org/developer/barbican

The source for the developer documentation lives in the main Barbican repo in RST format https://github.com/openstack/barbican/tree/master/doc/source

TODO: Document new plugin guidelines

python-barbicanclient
python-barbicanclient developer documentation is aimed at developers consuming the library in their own applications. Currently the client is documented in the CloudKeep fork's wiki https://github.com/cloudkeep/python-barbicanclient/wiki

TODO: Migrate docs to RST format in the python-barbicanclient repo

TODO: Configure gates to publish docs to http://docs.openstack.org/developer/python-barbicanclient

Other Guides
These are OpenStack-wide (not project-specific) guides that may require additional chapters to include Barbican.

Operations Guide
Source is found at https://github.com/openstack/operations-guide and is published to http://docs.openstack.org/ops

Security Guide
Source is found at https://github.com/openstack/security-doc and is published to http://docs.openstack.org/sec

Malini may have started work on adding Barbican to this guide?

Training Guides
Source is found at https://github.com/openstack/training-guides