river-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tom Hobbs <tvho...@googlemail.com>
Subject Re: Website, docuemntation links, and river/src-doc/static/index.html
Date Mon, 13 Dec 2010 10:07:36 GMT
The "Release Notes" that come along with the Jini specs that I
recently put into staging, aren't (I think) "release notes" in the
traditional sense.  At least not all of them.  There's some real
nuggets of information in them that need to appear under a title other
than "Release notes".

With regards to what goes into our releases, the release notes as
generated out of Jira and anything else that we've been doing in the
past.  The RNs as described above don't necessarily fit into that

I don't know about markdown and javadocs, I do want to be able to host
the javadocs (automatically, as much as possible) on the website and
update them everytime we do a new release.  The Jini Specs should have
absolute links in them to refer to the most up-to-date javadocs.  We
can provide additional downloads for the javadocs (or include it in
the release download if we think that's necessary.)  I'm not convinced
that the Jini Spec needs to be included in each release, although a
single downloadable package of the stuff would be nice.

Can we make it so that Hudson generates the Javadoc, and for a release
build, copies the Javadoc up into our website area?  The Javadoc could
also be zipped and made available from the Downloads page.  I don't
think that having the Javadoc in a different CSS/style thing to our
website is a big problem, in fact having non-matching Javadocs is
pretty common - from what I've seen elsewhere.

To summarise, my thoughts would be:
- Hudson to build the Javadoc from the source as normal HTML
- Hudson to copy the Javadoc HTML to somewhere that it can be served
by our website
- Hudson to create a ZIP of the Javadoc HTML ready for download
- Hudson to create the release containing binaries/source and release
notes and made ready for download from website
- Jini Specifications (and other documentation) to be in markdown
format on the website and contain absolute links to the most
up-to-date Javadocs
- Jini Specifications (and other documentation) to be taken from the
HTML site SVN, zipped and made available for download

On Mon, Dec 13, 2010 at 12:56 AM, Peter Firmstone <jini@zeus.net.au> wrote:
> The standards and release notes contain links to the build generated
> javadoc, built from java source.
> Is it possible to generate javadoc in the markdown format from the source
> code?  Or can markdown generate javadoc?
> If we could, then we could pull the website from it's svn path, and pull the
> standards, release notes and javadoc from river/trunk.
> This looks interesting: http://code.google.com/p/markdown-doclet/
> I think we currently access the javadoc from hudson builds for our website,
> but this isn't suitable for our release.  It would be nice if we could
> satisfy the website and the release with one source, since this reduces
> maintenance.
> I'm not sure what the way forward is at the moment, it requires some more
> thought.
> Cheers,
> Peter.
> Sim IJskes - QCG wrote:
>> On 12/12/2010 12:12 PM, Peter Firmstone wrote:
>>> Ok, sounds logical, when you checkout and build River, all the
>>> documentation is build able from ant, which is then included in the
>>> build that I release, so the copy we build for the website should also
>>> be buildable from ant? Does this mean we need a new tool in our lib's to
>>> build the docs?
>> Could be, yes. We could decide to include the docs in original markdown
>> format, or scrape them from the website, or convert them to html by
>> markdown. The only quick solutions that i see are include the original
>> mdtext files, or pull the converted mdtext files from the svn repo that
>> contains the website just before publishing (all html).
>> Gr. Sim
>> the chain is as follow for ASF CMS:
>> mdtext in svn
>> stage:
>> convert to html
>> store html in website repo
>> checkout to staging website
>> publish:
>> copy html in website repo to other repo dir
>> chechout to production website (all the mirrors)

View raw message