Open Stack

> 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. :-)

> 
> Doug
> 
> 

Tremendously helpful...thanks again.

- Phil