forrest-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tim Williams <william...@gmail.com>
Subject Re: Adding site documentation to project
Date Fri, 23 Sep 2011 20:36:37 GMT
On Fri, Sep 23, 2011 at 4:05 PM, lewis john mcgibbney
<lewis.mcgibbney@gmail.com> wrote:
> Hi again,
>
> I'm back working on this and could do with some pointers. Please see below
> for some of the keys areas.
>
> I've looked closely at your references and read both the forrestbot "svn"
> workstage and forrestbot automated build and deploying documentation. I
> understand completely how I want this to work and your suggestion for the
> process of editing sourc, updating the Nutch site, then an additional
> forrestbot task would update the new /docs directory within our SVN
> nutch/branches/branch-1.4/docs diretcory. This would then enable devs to
> simply svn update and any documentation changes would be updated. It would
> also provide an excellent way of shipping the generated docs with our next
> release. The parts I am struggling to understand are below:
>
>
> On Mon, Sep 19, 2011 at 3:27 AM, David Crossley <crossley@apache.org> wrote:
>>
>> lewis john mcgibbney wrote:
>> > Hi all,
>> >
>> > As a project, we are wanting to ship core documentation with the
>> > software
>> > distribution. Currently the Nutch site documentation can be found here
>> > [1],
>> > however we would like to start shipping it with our branch-1.4 [2] under
>> > a
>> > new /docs directory.
>> >
>> > I know this is rather trivial and that there must be documentation on it
>> > somewhere but I have not been able to get my hands on it from the
>> > Forrest
>> > site yet!
>> >
>> > Thanks for any pointers.
>> >
>> > [1] https://svn.apache.org/repos/asf/nutch/site/
>> > [2] https://svn.apache.org/repos/asf/nutch/branches/branch-1.4/
>>
>> I gather that you mean the "generated" relevant docs for that version.
>>
>> You could use the "Forrestbot" as we do for our Forrest project docs.
>>
>> http://forrest.apache.org/howto-forrestbot-svn.html
>> How to deploy documentation with the Forrestbot "svn" workstage
>>
>> In our case we deploy our generated documentation to SVN forrest/site
>> which gets 'svn up' on people.apache.org to publish our website.
>
> I 'think' this is already done. I am waiting for a reply from the more
> experienced dev's to give me insight into how committed changes to the site
> source are actually fed through to nutch.apache.org. As I know of no other
> method for doing this other than the one your specified, I am going on the
> assumption that this is already in place.
>
>>
>> The Nutch project could do that too for your website docs.
>
> Excellent, this is now my intention :0)
>
>>
>> Then have another "Forrestbot buildfile" which deploys the relevant
>> docs to SVN nutch/branches/branch-1.4
>
> How does this task get executed? If my comments as above are correct, this
> appears to be the main task at hand, therefore I am trying to find out where
> the additional buildfile is located and if this process can be triggered
> should there be any update to the site documentation e.g. a commit from the
> dev's.

There's another build file, typically "publish.xml"[see our example 1]
that contains the details of where to publish it.  You might find it
easier to start with a condensed version of our own publishing
instructions[2] or slightly more verbose[3] and expand your reading as
necessary from there...  There's no "trigger" to update them, but
they're periodically pulled - it looks like your latest footer change,
for example, was already pulled - sorry, I don't know the detailed
mechanics of that arrangement.

You've done plenty of research, ask away:)
--tim

[1] - http://svn.apache.org/repos/asf/forrest/trunk/site-author/publish.xml
[2] - http://svn.apache.org/repos/asf/forrest/trunk/etc/publishing_our_site.txt
[3] - http://forrest.apache.org/procedures/How_to_publish_docs.html

Mime
View raw message