[openstack-dev] [Ceilometer] Updating ceilometer developer documentation at docs.openstack.org
doug.hellmann at dreamhost.com
Thu Apr 25 12:07:51 UTC 2013
On Wednesday, April 24, 2013, Neal, Phil (Cloud Services) wrote:
> > On Tue, Apr 23, 2013 at 1:20 PM, Neal, Phil (Cloud Services)
> > > The documentation on how to make updates to the content at
> > > http://docs.openstack.org/developer/ceilometer/... doesn't seem to
> > > exist, so I'm hoping that someone can shed some light on the
> >> or point me to the right spot...
> > >
> > > Here's what I'm running into:
> > >
> > > 1. It looks like we're maintaining documentation in our Ceilometer
> > > (https://github.com/openstack/ceilometer vs. the centralized set
> >> https://github.com/openstack/openstack-manuals.git). No problems
> >> just need confirmation.
> > Yes. Ceilometer has just become integrated, and before then we were
> > maintaining our own docs. Now we are going to be working with the docs
> > team to integrate with the other manuals. In the mean time, we agreed to
> > continue adding docs to the existing source files so we could merge it
> all at
> > one time, when ready.
> Makes sense. I'm betting the release/update process will change when that
For the docs that move into the repo managed by the doc team, yes. The
developer docs will stay where they are.
> >> 2. It seems like the correct approach is to make edits as needed
> to the
> > > content ceilometer/docs/source directory, then run the Sphinx
> > > html" command to generate the html files. I'm running into a host
> > > errors, though, so I'm questioning if this is the right tool.
> > You'll need a system with ceilometer and its dependencies installed, and
> > then you should run "python setup.py build_sphinx" to make sure all of
> > auto-generated files are created.
> FWIW, the quickest way to install the dependencies (short of a full
> Devstack deployment) seems to be by running pip install against the
> test-requires file. I was able to run both build_sphinx and the Sphinx
> command "make html".
That sounds about right.
> > > 3. I'm not understanding the connection between the content of the
> > > files and what appears on the web site...it seems like there's some
> > > content that's getting generated that doesn't exist in the code or
> >> .rst files....is it black magic?
> > There are some auto-doc directives used to pull text in from the
> > documentation embedded in the source code. That's especially the case for
> > the web API documentation. You shouldn't need to worry about any of that
> > for the changes you want, except that you need to be able to install
> > ceilometer in order for it to work.
> Agreed, I just skipped past that to add reST-formatted text in the
> appropriate spots. No need to become an expert at this point. :-)
> > Doug
> Tremendously helpful...thanks again.
Thanks for working on the docs!
> - Phil
> OpenStack-dev mailing list
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the OpenStack-dev