forrest-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From lewis john mcgibbney <lewis.mcgibb...@gmail.com>
Subject Re: Adding site documentation to project
Date Mon, 26 Sep 2011 16:53:55 GMT
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*

Mime
View raw message