Mailing List Archive

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.

The Nutch project could do that too for your website docs.

Then have another "Forrestbot buildfile" which deploys the relevant
docs to SVN nutch/branches/branch-1.4

-David

Thank you David, I'll work on this basis and hopefully get it sorted out.

Thanks

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.
>
> The Nutch project could do that too for your website docs.
>
> Then have another "Forrestbot buildfile" which deploys the relevant
> docs to SVN nutch/branches/branch-1.4
>
> -David
>



--
*Lewis*

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.

Apologies if this seems I have not done my research, but I am just not
getting it...

Thanks again for any help that can be offered.

>
> -David
>



--
*Lewis*

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

Tim Williams wrote:
> lewis john mcgibbney
> <lewis.mcgibbney@gmail.com> wrote:
> >
> > 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:
> >
> > David Crossley wrote:
> >> lewis john mcgibbney wrote:
> >> >
> >> > 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.

Your generated docs are committed to the "site/publish/" directory.
On the server it will be either an automated cron job by one
or more of your committers doing 'svn up' in your nutch.a.o space
(this is the old way like our Forrest project still does)
or it will be under "svnpubsub".

> >> [ snip]
> >> 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

Sure, Thanks Tim.

Also see the orginal document that i referenced at
http://forrest.apache.org/howto-forrestbot-svn.html#follow

Nutch needs to create your own buildfile. When each committer wants
to publish their changes, they run the local forrestbot "build"
as explained. If all is well then commit their source edits
and then do the "deploy" step.

-David

thank you both for the help on this one. It is greatly appreciated.

Lewis

On Mon, Sep 26, 2011 at 12:32 AM, David Crossley <crossley@apache.org>wrote:

> Tim Williams wrote:
> > lewis john mcgibbney
> > <lewis.mcgibbney@gmail.com> wrote:
> > >
> > > 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:
> > >
> > > David Crossley wrote:
> > >> lewis john mcgibbney wrote:
> > >> >
> > >> > 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.
>
> Your generated docs are committed to the "site/publish/" directory.
> On the server it will be either an automated cron job by one
> or more of your committers doing 'svn up' in your nutch.a.o space
> (this is the old way like our Forrest project still does)
> or it will be under "svnpubsub".
>
> > >> [ snip]
> > >> 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
>
> Sure, Thanks Tim.
>
> Also see the orginal document that i referenced at
> http://forrest.apache.org/howto-forrestbot-svn.html#follow
>
> Nutch needs to create your own buildfile. When each committer wants
> to publish their changes, they run the local forrestbot "build"
> as explained. If all is well then commit their source edits
> and then do the "deploy" step.
>
> -David
>



--
*Lewis*