You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@river.apache.org by Wade Chandler <hw...@yahoo.com> on 2010/12/09 16:05:07 UTC
Website, docuemntation links, and river/src-doc/static/index.html
All,
I believe it would be good to some how work in a link to the latest builds
river/src-doc/static/index.html on the web site under the documentation links.
This could possibly be per a link "Development Release Documentation" or
"Release Documentation" or maybe "Documentation and Specifications"; perhaps
better and more simply "River Documentation". It may not be formatted as the
rest of the site yet, but it still gets that valuable information out there for
anyone just now looking at River with a couple clicks on the web site. The
specifications really get to the heart of what it is and tries to accomplish in
my opinion. Too there are the manual pages plus the getting started page though
some of the lower links don't work (manual pages being some), and I assume this
is due to part of the build not copying things around and generating all the
JavaDocs. I haven't had time to look at the build to see if there is a target
which will copy those docs around an fix those issues or not. Regardless, I
think those things would be good to have visible directly from the web site
without one having to download anything first.
Thoughts?
Thanks,
Wade
==================
Wade Chandler
Software Engineer and Developer
NetBeans Dream Team Member and Contributor
http://wiki.netbeans.org/wiki/view/NetBeansDreamTeam
http://www.netbeans.org
Re: Website, docuemntation links, and river/src-doc/static/index.html
Posted by Peter Firmstone <ji...@zeus.net.au>.
The doc's look like they're in a state of transition in the current
build, they don't look ready for release, can you or Sim let me know
when they are? No pressure, take your time, if you need some help let
me know, it's probably best not to let too many cooks spoil the broth
for now though. Once you're done, I'll add the jira generated release
notes.
It doesn't look like I'll get time to solve the Solaris 10 sparc Java 6
bugs, they do appear to be important security issues for sparc, so I'll
document their existence in the release notes.
Cheers,
Peter.
Peter Firmstone wrote:
> Interesting.
>
> When we distribute our release artifact, the release notes contain the
> spec, which references the api docs contained in the release
> artifact. I spent quite a bit of time tidying up last release. I
> know your doing this for the website, so it's a different concern.
> But I wonder if we can have relative links, or something, so we don't
> end up diverging the website spec docs from those we distribute with
> the release? Perhaps we can populate the website with the last
> release API for the spec to reference, rather than linking to the
> latest hudson build?
> Don't know really, just thinking aloud.
>
> Keep up the good work.
>
> Cheers,
>
> Peter.
>
>
>
> Tom Hobbs wrote:
>> Hi Wade,
>>
>> Thanks for the suggestion. I've just recently uploaded all of the
>> original Jini Specs and other documentation into our new CMS. It's
>> still in the staging environment at the moment because I still haven't
>> converted it all to our CMS markup from it's original HTML.
>>
>> You're absolutely right, a link to the specs straight from the home
>> page is a good thing to have. Currently I'm removing all the links to
>> the API docs from the specs, mostly because I know that they'll all be
>> broken. I have a cunning plan to add links from every class mentioned
>> in the specs to the latest API docs using sed and grep - and probably
>> awk as well.
>>
>> A link straight to the API docs from the home page would also be good.
>>
>> Cheers,
>>
>> Tom
>>
>> On Thu, Dec 9, 2010 at 3:05 PM, Wade Chandler
>> <hw...@yahoo.com> wrote:
>>
>>> All,
>>>
>>> I believe it would be good to some how work in a link to the latest
>>> builds
>>> river/src-doc/static/index.html on the web site under the
>>> documentation links.
>>> This could possibly be per a link "Development Release
>>> Documentation" or
>>> "Release Documentation" or maybe "Documentation and Specifications";
>>> perhaps
>>> better and more simply "River Documentation". It may not be
>>> formatted as the
>>> rest of the site yet, but it still gets that valuable information
>>> out there for
>>> anyone just now looking at River with a couple clicks on the web
>>> site. The
>>> specifications really get to the heart of what it is and tries to
>>> accomplish in
>>> my opinion. Too there are the manual pages plus the getting started
>>> page though
>>> some of the lower links don't work (manual pages being some), and I
>>> assume this
>>> is due to part of the build not copying things around and generating
>>> all the
>>> JavaDocs. I haven't had time to look at the build to see if there is
>>> a target
>>> which will copy those docs around an fix those issues or not.
>>> Regardless, I
>>> think those things would be good to have visible directly from the
>>> web site
>>> without one having to download anything first.
>>>
>>> Thoughts?
>>>
>>> Thanks,
>>>
>>> Wade
>>>
>>> ==================
>>> Wade Chandler
>>> Software Engineer and Developer
>>> NetBeans Dream Team Member and Contributor
>>>
>>>
>>> http://wiki.netbeans.org/wiki/view/NetBeansDreamTeam
>>> http://www.netbeans.org
>>>
>>>
>>
>>
>
>
Re: Website, docuemntation links, and river/src-doc/static/index.html
Posted by Peter Firmstone <ji...@zeus.net.au>.
Tom Hobbs wrote:
>>> I've been changing the Jini Specs from HTML into a style which matches
>>> the rest of our website - i.e. markdown. In retrospect, maybe that
>>> wasn't the right thing to do, because (as has been pointed out) we'll
>>> need to convert the specs back from markdown into HTML for easy
>>> download/reading on part of the users.
>>>
>>>
>> Actually don't rush into reversing your changes, lets think it through,
>> Markdown is intended to be viewable as text, we've got a doc-src directory,
>> we could keep your changes and include markdown as a build dependency.
>>
>
> I've not had the opportunity to do much of anything. I can leave what
> I've done there, and just put the HTML back in without any problem.
>
>
>>> As I mention in this email, having Javadocs in a different format to
>>> the website is okay, and I guess that having the Jini Spec in a
>>> different format is okay also. So I'm going to rollback my changes
>>> for the Jini Spec only. This way we can just pull it off the site SVN
>>> for easy packaging in/with the release.
>>>
>>>
>> Ok, can we go in the other direction though? I like to build it locally,
>> make changes, update and check links etc.
>>
>
> I'm really not sure what we're talking about any more. You like to
> build what locally? The Jini Spec? River? The JavaDoc?
>
My current practice is to edit the doc's in trunk and review them
locally and build the javadoc, check the links and commit changes.
> I doubt that the Jini Spec will change regularly, so having it
> separate from the source isn't a problem - in my opinion. Please
> correct me if I'm wrong. Besides the source, the only thing that
> might be changed vaguely regularly is the JavaDoc.
>
I intend to better document Discovery and constraints.
I'm happy for you to put things back how they were if that's what you want.
>
>> Can it be staged via an ant task.
>>
>> Still a markdown javadoc tool sounds neat, makes source code easier to read
>> too.
>>
>
> How does markdown JavaDoc make the code easier to read?
If you need to add html markup, markdown is easier to read.
> In Eclipse
> (at least) the documentation tips you get are JavaDoc based on the
> source code you've selected or are hovering over etc. I read the
> above as formatting the JavaDoc into markdown? Or are you saying
> there's a tool for generating markdown based on Javadocs?
No, it generates javadocs from markdown in your source code, I thought
it was interesting, the tool also creates UML diagrams in your javadoc.
> How would
> that be any different from any other authomated tool for converting
> HTML to markdown?
>
> I.e. generate the JavaDoc as normal, then convert the resultant HTML
> into Markdown.
>
> I'm concerned that my efforts to convert the Jini Spec into Markdown
> have propagated the idea that this is what we want to do. I think
> that it is/was a mistake.
>
> Keeping both the Jini Spec and the JavaDoc as plain old HTML, and
> being able to distribute one or more ZIPs containing those HTML files
> is, I think, the way forward. It also happens to be closest to what
> we do now. The only caveat is that the links from the Jini Spec to
> the Javadoc would be absolute links pointing to the JavaDoc hosted on
> the River site.
>
>
>> If there is an ant task to assist developers to download the required gpl
>> libs like the markdown javadoclet, and jtreg for developers, then we aren't
>> distributing them with the release, so not breaking any rules ;)
>>
>> Cheers, Peter.
>>
>>> The other bits of documentation that came along with the JS I think
>>> should still be converted to markdown because I don't think they're
>>> really things that are going to need downloading and distributing
>>> outside of the website.
>>>
>>> Is that okay?
>>>
>>>
>>> On Mon, Dec 13, 2010 at 10:07 AM, Tom Hobbs <tv...@googlemail.com>
>>> wrote:
>>>
>>>
>>>> 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
>>>> criteria.
>>>>
>>>> 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 <ji...@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)
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>
>>>
>>
>
>
Re: Website, docuemntation links, and river/src-doc/static/index.html
Posted by Tom Hobbs <tv...@googlemail.com>.
>> I've been changing the Jini Specs from HTML into a style which matches
>> the rest of our website - i.e. markdown. In retrospect, maybe that
>> wasn't the right thing to do, because (as has been pointed out) we'll
>> need to convert the specs back from markdown into HTML for easy
>> download/reading on part of the users.
>>
>
> Actually don't rush into reversing your changes, lets think it through,
> Markdown is intended to be viewable as text, we've got a doc-src directory,
> we could keep your changes and include markdown as a build dependency.
I've not had the opportunity to do much of anything. I can leave what
I've done there, and just put the HTML back in without any problem.
>> As I mention in this email, having Javadocs in a different format to
>> the website is okay, and I guess that having the Jini Spec in a
>> different format is okay also. So I'm going to rollback my changes
>> for the Jini Spec only. This way we can just pull it off the site SVN
>> for easy packaging in/with the release.
>>
>
> Ok, can we go in the other direction though? I like to build it locally,
> make changes, update and check links etc.
I'm really not sure what we're talking about any more. You like to
build what locally? The Jini Spec? River? The JavaDoc?
I doubt that the Jini Spec will change regularly, so having it
separate from the source isn't a problem - in my opinion. Please
correct me if I'm wrong. Besides the source, the only thing that
might be changed vaguely regularly is the JavaDoc.
> Can it be staged via an ant task.
>
> Still a markdown javadoc tool sounds neat, makes source code easier to read
> too.
How does markdown JavaDoc make the code easier to read? In Eclipse
(at least) the documentation tips you get are JavaDoc based on the
source code you've selected or are hovering over etc. I read the
above as formatting the JavaDoc into markdown? Or are you saying
there's a tool for generating markdown based on Javadocs? How would
that be any different from any other authomated tool for converting
HTML to markdown?
I.e. generate the JavaDoc as normal, then convert the resultant HTML
into Markdown.
I'm concerned that my efforts to convert the Jini Spec into Markdown
have propagated the idea that this is what we want to do. I think
that it is/was a mistake.
Keeping both the Jini Spec and the JavaDoc as plain old HTML, and
being able to distribute one or more ZIPs containing those HTML files
is, I think, the way forward. It also happens to be closest to what
we do now. The only caveat is that the links from the Jini Spec to
the Javadoc would be absolute links pointing to the JavaDoc hosted on
the River site.
> If there is an ant task to assist developers to download the required gpl
> libs like the markdown javadoclet, and jtreg for developers, then we aren't
> distributing them with the release, so not breaking any rules ;)
>
> Cheers, Peter.
>>
>> The other bits of documentation that came along with the JS I think
>> should still be converted to markdown because I don't think they're
>> really things that are going to need downloading and distributing
>> outside of the website.
>>
>> Is that okay?
>>
>>
>> On Mon, Dec 13, 2010 at 10:07 AM, Tom Hobbs <tv...@googlemail.com>
>> wrote:
>>
>>>
>>> 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
>>> criteria.
>>>
>>> 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 <ji...@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)
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>
>>>>
>>
>>
>
>
Re: Website, docuemntation links, and river/src-doc/static/index.html
Posted by Peter Firmstone <ji...@zeus.net.au>.
Tom Hobbs wrote:
> Speaking to Sim just now, he raised something that I skipped past entirely.
>
> I've been changing the Jini Specs from HTML into a style which matches
> the rest of our website - i.e. markdown. In retrospect, maybe that
> wasn't the right thing to do, because (as has been pointed out) we'll
> need to convert the specs back from markdown into HTML for easy
> download/reading on part of the users.
>
Actually don't rush into reversing your changes, lets think it through,
Markdown is intended to be viewable as text, we've got a doc-src
directory, we could keep your changes and include markdown as a build
dependency.
> As I mention in this email, having Javadocs in a different format to
> the website is okay, and I guess that having the Jini Spec in a
> different format is okay also. So I'm going to rollback my changes
> for the Jini Spec only. This way we can just pull it off the site SVN
> for easy packaging in/with the release.
>
Ok, can we go in the other direction though? I like to build it
locally, make changes, update and check links etc.
Can it be staged via an ant task.
Still a markdown javadoc tool sounds neat, makes source code easier to
read too.
If there is an ant task to assist developers to download the required
gpl libs like the markdown javadoclet, and jtreg for developers, then we
aren't distributing them with the release, so not breaking any rules ;)
Cheers, Peter.
> The other bits of documentation that came along with the JS I think
> should still be converted to markdown because I don't think they're
> really things that are going to need downloading and distributing
> outside of the website.
>
> Is that okay?
>
>
> On Mon, Dec 13, 2010 at 10:07 AM, Tom Hobbs <tv...@googlemail.com> wrote:
>
>> 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
>> criteria.
>>
>> 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 <ji...@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)
>>>>
>>>>
>>>>
>>>>
>>>>
>>>>
>>>>
>>>
>
>
Re: Website, docuemntation links, and river/src-doc/static/index.html
Posted by Tom Hobbs <tv...@googlemail.com>.
Speaking to Sim just now, he raised something that I skipped past entirely.
I've been changing the Jini Specs from HTML into a style which matches
the rest of our website - i.e. markdown. In retrospect, maybe that
wasn't the right thing to do, because (as has been pointed out) we'll
need to convert the specs back from markdown into HTML for easy
download/reading on part of the users.
As I mention in this email, having Javadocs in a different format to
the website is okay, and I guess that having the Jini Spec in a
different format is okay also. So I'm going to rollback my changes
for the Jini Spec only. This way we can just pull it off the site SVN
for easy packaging in/with the release.
The other bits of documentation that came along with the JS I think
should still be converted to markdown because I don't think they're
really things that are going to need downloading and distributing
outside of the website.
Is that okay?
On Mon, Dec 13, 2010 at 10:07 AM, Tom Hobbs <tv...@googlemail.com> wrote:
> 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
> criteria.
>
> 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 <ji...@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)
>>>
>>>
>>>
>>>
>>>
>>>
>>
>>
>
Re: Website, docuemntation links, and river/src-doc/static/index.html
Posted by Patricia Shanahan <pa...@acm.org>.
Sim IJskes - QCG wrote:
> On 13-12-10 11:07, Tom Hobbs wrote:
>> 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
>
> To create a secure path from hudson to the website might not be that
> easy. We could prepare zipfiles in hudson, and at the moment of release
> have a small manual procedure to go through to publish it.
I see you have started a web page for the release process. A manual step
like that seems much more acceptable if it appears in a check list, so
that it won't get forgotten.
Are there any other projects using both the same web site building
process and javadoc? If so, what do they do? Perhaps the mentors could
suggest the most similar project to River in terms of process, so that
one of us can subscribe to their developer mailing list, review their
web pages etc.?
Patricia
Patricia
Re: Website, docuemntation links, and river/src-doc/static/index.html
Posted by Sim IJskes - QCG <si...@qcg.nl>.
On 13-12-10 11:07, Tom Hobbs wrote:
> 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
To create a secure path from hudson to the website might not be that
easy. We could prepare zipfiles in hudson, and at the moment of release
have a small manual procedure to go through to publish it.
Gr. Sim
--
QCG, Software voor het MKB, 071-5890970, http://www.qcg.nl
Quality Consultancy Group b.v., Leiderdorp, Kvk Den Haag: 28088397
Re: Website, docuemntation links, and river/src-doc/static/index.html
Posted by Tom Hobbs <tv...@googlemail.com>.
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
criteria.
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 <ji...@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)
>>
>>
>>
>>
>>
>>
>
>
Re: Website, docuemntation links, and river/src-doc/static/index.html
Posted by Peter Firmstone <ji...@zeus.net.au>.
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)
>
>
>
>
>
>
Re: Website, docuemntation links, and river/src-doc/static/index.html
Posted by Sim IJskes - QCG <si...@qcg.nl>.
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)
Re: Website, docuemntation links, and river/src-doc/static/index.html
Posted by Peter Firmstone <ji...@zeus.net.au>.
Sim IJskes - QCG wrote:
> On 12/12/2010 06:29 AM, Peter Firmstone wrote:
>> When we distribute our release artifact, the release notes contain the
>> spec, which references the api docs contained in the release artifact. I
>> spent quite a bit of time tidying up last release. I know your doing
>> this for the website, so it's a different concern. But I wonder if we
>> can have relative links, or something, so we don't end up diverging the
>> website spec docs from those we distribute with the release? Perhaps we
>> can populate the website with the last release API for the spec to
>> reference, rather than linking to the latest hudson build?
>> Don't know really, just thinking aloud.
>
> There can only be one source. So if we are converting the specs to
> mdtext to publish on the website, and we need to package them in a
> release, we should derive them from the mdtext ones, or refer to them.
>
> Release notes should be notes about the specific release, the specs
> are part of the release. We should treat them as separate units.
>
> Gr. Sim
>
>
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?
Cheers,
Peter.
Re: Website, docuemntation links, and river/src-doc/static/index.html
Posted by Sim IJskes - QCG <si...@qcg.nl>.
On 12/12/2010 06:29 AM, Peter Firmstone wrote:
> When we distribute our release artifact, the release notes contain the
> spec, which references the api docs contained in the release artifact. I
> spent quite a bit of time tidying up last release. I know your doing
> this for the website, so it's a different concern. But I wonder if we
> can have relative links, or something, so we don't end up diverging the
> website spec docs from those we distribute with the release? Perhaps we
> can populate the website with the last release API for the spec to
> reference, rather than linking to the latest hudson build?
> Don't know really, just thinking aloud.
There can only be one source. So if we are converting the specs to
mdtext to publish on the website, and we need to package them in a
release, we should derive them from the mdtext ones, or refer to them.
Release notes should be notes about the specific release, the specs are
part of the release. We should treat them as separate units.
Gr. Sim
Re: Website, docuemntation links, and river/src-doc/static/index.html
Posted by Peter Firmstone <ji...@zeus.net.au>.
Interesting.
When we distribute our release artifact, the release notes contain the
spec, which references the api docs contained in the release artifact.
I spent quite a bit of time tidying up last release. I know your doing
this for the website, so it's a different concern. But I wonder if we
can have relative links, or something, so we don't end up diverging the
website spec docs from those we distribute with the release? Perhaps we
can populate the website with the last release API for the spec to
reference, rather than linking to the latest hudson build?
Don't know really, just thinking aloud.
Keep up the good work.
Cheers,
Peter.
Tom Hobbs wrote:
> Hi Wade,
>
> Thanks for the suggestion. I've just recently uploaded all of the
> original Jini Specs and other documentation into our new CMS. It's
> still in the staging environment at the moment because I still haven't
> converted it all to our CMS markup from it's original HTML.
>
> You're absolutely right, a link to the specs straight from the home
> page is a good thing to have. Currently I'm removing all the links to
> the API docs from the specs, mostly because I know that they'll all be
> broken. I have a cunning plan to add links from every class mentioned
> in the specs to the latest API docs using sed and grep - and probably
> awk as well.
>
> A link straight to the API docs from the home page would also be good.
>
> Cheers,
>
> Tom
>
> On Thu, Dec 9, 2010 at 3:05 PM, Wade Chandler
> <hw...@yahoo.com> wrote:
>
>> All,
>>
>> I believe it would be good to some how work in a link to the latest builds
>> river/src-doc/static/index.html on the web site under the documentation links.
>> This could possibly be per a link "Development Release Documentation" or
>> "Release Documentation" or maybe "Documentation and Specifications"; perhaps
>> better and more simply "River Documentation". It may not be formatted as the
>> rest of the site yet, but it still gets that valuable information out there for
>> anyone just now looking at River with a couple clicks on the web site. The
>> specifications really get to the heart of what it is and tries to accomplish in
>> my opinion. Too there are the manual pages plus the getting started page though
>> some of the lower links don't work (manual pages being some), and I assume this
>> is due to part of the build not copying things around and generating all the
>> JavaDocs. I haven't had time to look at the build to see if there is a target
>> which will copy those docs around an fix those issues or not. Regardless, I
>> think those things would be good to have visible directly from the web site
>> without one having to download anything first.
>>
>> Thoughts?
>>
>> Thanks,
>>
>> Wade
>>
>> ==================
>> Wade Chandler
>> Software Engineer and Developer
>> NetBeans Dream Team Member and Contributor
>>
>>
>> http://wiki.netbeans.org/wiki/view/NetBeansDreamTeam
>> http://www.netbeans.org
>>
>>
>
>
Re: Website, docuemntation links, and river/src-doc/static/index.html
Posted by Tom Hobbs <tv...@googlemail.com>.
Hi Wade,
Thanks for the suggestion. I've just recently uploaded all of the
original Jini Specs and other documentation into our new CMS. It's
still in the staging environment at the moment because I still haven't
converted it all to our CMS markup from it's original HTML.
You're absolutely right, a link to the specs straight from the home
page is a good thing to have. Currently I'm removing all the links to
the API docs from the specs, mostly because I know that they'll all be
broken. I have a cunning plan to add links from every class mentioned
in the specs to the latest API docs using sed and grep - and probably
awk as well.
A link straight to the API docs from the home page would also be good.
Cheers,
Tom
On Thu, Dec 9, 2010 at 3:05 PM, Wade Chandler
<hw...@yahoo.com> wrote:
> All,
>
> I believe it would be good to some how work in a link to the latest builds
> river/src-doc/static/index.html on the web site under the documentation links.
> This could possibly be per a link "Development Release Documentation" or
> "Release Documentation" or maybe "Documentation and Specifications"; perhaps
> better and more simply "River Documentation". It may not be formatted as the
> rest of the site yet, but it still gets that valuable information out there for
> anyone just now looking at River with a couple clicks on the web site. The
> specifications really get to the heart of what it is and tries to accomplish in
> my opinion. Too there are the manual pages plus the getting started page though
> some of the lower links don't work (manual pages being some), and I assume this
> is due to part of the build not copying things around and generating all the
> JavaDocs. I haven't had time to look at the build to see if there is a target
> which will copy those docs around an fix those issues or not. Regardless, I
> think those things would be good to have visible directly from the web site
> without one having to download anything first.
>
> Thoughts?
>
> Thanks,
>
> Wade
>
> ==================
> Wade Chandler
> Software Engineer and Developer
> NetBeans Dream Team Member and Contributor
>
>
> http://wiki.netbeans.org/wiki/view/NetBeansDreamTeam
> http://www.netbeans.org
>