Re: [GMG-Devel] docs: Debian / rpm-based distros and sudo / root

[Christopher Allan Webber]

Jim Campbell writes:

> Hi All,

Hi Jim!

> As things are now, our docs start out by saying, "If you're on a
> Debian-based system, do this . . . but if you're on a RPM-based system
> do that . . . " but those types of distinctions end after the mention of
> specific python packages (i.e., there are no Fedora/RHEL/CentOS
> instructions for which postgres packages to install). Based on this,
> should we include instructions for the Fedora/RHEL/CentOS family in the
> official docs, or should we focus just on Debian in the official docs?
> Right now, the instructions are 1/4-baked on the Fedora/RHEL/CentOS
> side.  

I think we should support them.

> Personally, I would like to include that family of distros as an
> alternate, but don't want to muck-up the docs. It would be better to
> have a documentation set that people can follow-along w/o having to
> constantly "do this" for one platform or "do that" for another platform
> [0].  For now, I think it would be better to provide top-notch
> instructions for Debian, though. What do folks think?  This would mean
> removing the notes about RPM-based distros in the start, and moving
> those docs elsewhere. If folks would like to include Fedora/RHEL/CentOS
> in the official docs, I could add-in my Fedora/RHEL/CentOS stuff.  I’m
> not sure if it’s ready, though.

What do other projects do?  I wonder sometimes why things seem so much
harder for our docs than for other projects... maybe it's just because
end-user web applications are rare and all of them would be this hard
for ours, but maybe there is something clearer we could do better.

... So, one crazy idea I've had is to set up some custom sphinx
extension for distro/OS specific instructions, maybe looking like

.----------------------------------------------.
| V Debian (Ubuntu/Trisquel/Gnewsense)         |
|----------------------------------------------|
|   sudo apt-get install monkeys               |
|==============================================|
| > Fedora (RedHat/CentOS/Foo)                 |
|==============================================|
| > OS X                                       |
'----------------------------------------------'

(see http://pamrel.lu/3cacf/ if not using fixed width fonts)

The idea is once you expand the section for your setup, it expands the
rest.

Not sure how hard this would be to implement.  You can add special
syntax/forms to Sphinx, so I think not too hard from the Sphinx side,
but it would also require adding JS.  Not sure how it would affect the
texinfo generation, either.

Maybe not worth the time but I thought I'd throw it out there...

> Also, there are alternate instructions for sudo and root. I’d like to
> eliminate the root-based instructions, and just feature use of sudo
> where appropriate.  (I was actually the one who did things this way . .
> . in going through it, I don’t think it works well, though  : ).  If
> anyone prefers to use root, they could certainly sort out the
> differences and remove the “sudo” command as they go through things. 

I don't have a strong preference.

> Jim
>
> [0] The OpenStack docs are transitioning fully from DocBook to
> Python-Sphinx, and they're working on this problem in Python-Sphinx. The
> conditional-related Sphinx features don’t quite do what they want, and
> they’re working on a sphinx extension to allow advanced, conditional
> builds of docs. With the stuff they’re working on, they would have a
> single rST/python-sphinx source document, but could build out the html
> instructions for Ubuntu using one build command, and build out the html
> instructions for Fedora/RHEL/CentOS using another build command.  I
> think this would be nice to have for MediaGoblin in a later release.  

Ah okay!  So actually that kind of sounds like what we want.  Maybe we
should work with them?