openstack team mailing list archive

[Soren Hansen <soren@xxxxxxxxxxx>]

2011/4/17 Thomas Goirand <thomas@xxxxxxxxxx>:
> I have noticed that all binaries of Openstack nova / swift / glance, are
> going in /usr/bin, including daemons.

Yeah. That's where distutils puts scripts them by default. I'm sure
there's a way to coerce it into putting them somewhere else.

> As per the FSSH, daemons should go in /usr/sbin.

That was my gut feeling too, but I can't find anything in the FHS that
specicially speaks for daemons. Or is FSSH something else?

> In my Debian packaging, I've written few man pages, because it's
> forbidden in Debian to package things in /usr/bin or /usr/sbin without
> them.

I think "forbidden" is a bit of an exaggeration. It says "should" and
that missing man pages should be considered bugs.

This is actually why I'm generally against stub man pages. They make
it less obvious that there's work to do, but meh.

> I've already noticed that nova has a novamanage.1 which is generated by
> Sphinx. What would be the way to write the new man pages I'd like to
> add, in the same way? (BTW, as I wrote to Thierry in IRC, it should have
> been nova-manage.1 and not novamanage.1) Or would it be seen as
> acceptable to write man pages "by hand" (which I am comfortable doing)?
> What's the preferred way for the project(s)?

nova-manage is a bit special. Every (I think) other binary always does
the same thing (e.g. "act as an API server"), but takes half a
bajillion flags. nova-manage does a number of different things, which
I suppose is the reason it has special documentation magic.

We use python-gflags for our flag parsing and stuff, and gflags2man
can convert the flags descriptions to man pages, but it doesn't really
work for us, because we have a lot of conditional imports and stuff.
Anyway, the point is that there are existing tools that can mostly
generate man pages for us (automatically, so they'll be guaranteed to
be up-to-date), but there's some plumbing missing.

-- 
Soren Hansen        | http://linux2go.dk/
Ubuntu Developer    | http://www.ubuntu.com/
OpenStack Developer | http://www.openstack.org/