[openstack-dev] [Ceilometer] Updating ceilometer developer documentation at docs.openstack.org
Neal, Phil (Cloud Services)
phil.neal at hp.com
Wed Apr 24 21:05:55 UTC 2013
> On Tue, Apr 23, 2013 at 1:20 PM, Neal, Phil (Cloud Services)
> <phil.neal at hp.com> wrote:
> > 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 process
>> 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 repo
> > (https://github.com/openstack/ceilometer vs. the centralized set at
>> https://github.com/openstack/openstack-manuals.git). No problems there,
>> 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 happens?
>> 2. It seems like the correct approach is to make edits as needed to the
> > content ceilometer/docs/source directory, then run the Sphinx "make
> > html" command to generate the html files. I'm running into a host of
> > 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 the
> 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".
> > 3. I'm not understanding the connection between the content of the .rst
> > 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 the
>> .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. :-)
Tremendously helpful...thanks again.
More information about the OpenStack-dev