----- Original Message -----
From: "Nick Coghlan" <ncoghlan(a)redhat.com>
To: beaker-devel(a)lists.fedorahosted.org
Sent: Wednesday, October 30, 2013 12:29:14 PM
Subject: Re: [Beaker-devel] Current state of Beah's development and release process
On 10/30/2013 11:37 AM, Amit Saha wrote:
>
>
> ----- Original Message -----
>> From: "Nick Coghlan" <ncoghlan(a)redhat.com>
>> To: beaker-devel(a)lists.fedorahosted.org
>> Sent: Friday, October 25, 2013 10:26:16 AM
>> Subject: Re: [Beaker-devel] Current state of Beah's development and
>> release process
>>
>> On 10/23/2013 10:00 AM, Amit Saha wrote:
>>> Sounds fairly good to me. Are we also looking at *adding* additional
>>> documentation
>>> incrementally over time?
>>
>> For beah? Maybe - we still have a few bugs for aspects of the harness
>> that aren't currently well documented.
>
> I started the process of moving the Beah docs from beaker's repository to
> Beah's
> and reorganizing the existing Beah docs.
>
> The patch is here [1]. A new docs sub-directory is created under which
> Beah's current
> and future docs will live. The existing docs which have been moved from the
> top-level
> to this directory are in plain text format. New docs which have been
> written or moved
> from beaker's repo are in reStructuredText. I believe we will want to
> publish all docs
> as HTML files? If yes, what path do we go down? Create a sphinx project?
> That said, the TODO
> and README files will need some reformatting so that we have a consistent
> format across
> all the files.
Yeah, let's stick with the Sphinx based docs.
Done:
http://gerrit.beaker-project.org/#/c/2431/
> Regarding the contents, the README files can be worked upon to create a
> fairly usable user
> guide and the TODO file is a good place to start as far as a roadmap is
> concerned.
>
> Regarding publishing the contents (as hinted by Nick earlier), a "related
> projects" page
> will be setup on
beaker-project.org which will link to beah's docs and git
> repository (and
> over time will include other projects). How do we want to manage Beah's
> docs here? Do we go down
> the path of git submodules or is that too overly complicated for what we
> want here?
Dan and I were discussing this before he went on PTO, and we'd actually
like to cull most of the submodules we already have.
We're pretty sure the
beaker-project.org system has enough RAM allocated
to run Sphinx builds now, so we were thinking of replacing the
submodules with docs builds running directly on the server as a regular
cron job or a git commit hook on the respective branches. The only
submodule we'd keep would be the one for the master docs, since that
ties in with the rest of the release process.
(I think there's a task to set that up in the internal tracker already)
I thought about it a bit and looked around our current publishing setup. Here
is something that may work:
Create a post-receive hook in the Beah repository (on the server) which will
build the docs and copy it to a sub-directory under
beaker-project.org/htdocs as
something like
docs-beah or something. Thus, the beah docs will be accessible as
beaker-project.org/docs-beah/
How does that sound?
Best,
Amit.
--
Amit Saha <
http://echorand.me>
Infrastructure Engineering and Development
Red Hat, Inc.