Open Stack

On Wednesday, April 24, 2013, Neal, Phil (Cloud Services) wrote:

>
> > On Tue, Apr 23, 2013 at 1:20 PM, Neal, Phil (Cloud Services)
> > <phil.neal at hp.com <javascript:;>> 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?



 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
> "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".


That sounds about right.



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


Thanks for working on the docs!

Doug


>
> - Phil
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org <javascript:;>
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20130425/6284650c/attachment.html>