Open Stack

On 04/18/2011 05:44 AM, Soren Hansen wrote:
> 2011/4/17 Thomas Goirand <thomas at goirand.fr>:
>> 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?

Sorry. File Hierarchy Standard, or File System Hierarchy? I'm not sure,
but anyway, we are talking about the same thing! :)

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

"lintian -Ii" warns about it, so I fix it... As simple as that! :)
Also, for myself, I found difficult to know which binary accepts what
option, and I would have appreciate such documentation as well.

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

Nobody ever wrote we are going to leave things this way, writing in this
list is precisely to warn everyone that we do need more man pages work.

> other binary [...] takes half a bajillion flags.

Which is what I am worried about. At some point, we got to document that.

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

Ok, that's exactly what I wanted to know, thanks. I'll have a look in
about a week of time (after a short break this week).

On 04/18/2011 02:54 AM, Anne Gentle wrote:
> Hi Thomas -
> 
> I'd love you to write more man pages for the Nova project. The way I
> wrote the nova-manage man page was my first attempt to write a man page,
> and I basically wanted to keep the documentation in the doc directory,
> so I put it in doc/source. Sorry the file is named incorrectly, I didn't
> realize that.

No worries! :)

lintian (a Debian quality insurance tool) warned me about the
nova-manage binary not being documented, but it took me a long time to
realize what was going on. Not a big deal for me, as I did some renames
on the Debian packaging side of things, but I thought it was important
to write it in this list so that it could be fixed for everyone.

> I don't have a strong opinion on the matter, and I am not
> one to say "well we've always done it this way so..."

I'm ok whatever way you feel more comfortable, either by hand or
generated by some tool. If you are ok with a "by hand" thing, then I'll
right away move my man pages in the doc folder.

Mainly, I had to add at least stub man pages to have the package be
Debian policy compliant.

> If you do write man pages by hand, can they:
> a) be stored with the nova doc source?

Yes, my intention was to fix what I did and put it somewhere there.

> b) be reused across distros? (that is, you're not writing just for
> debian, right?)

That's my hope.

Thomas Goirand