river-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Peter Firmstone <j...@zeus.net.au>
Subject Re: Website, docuemntation links, and river/src-doc/static/index.html
Date Mon, 13 Dec 2010 21:23:41 GMT
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 <tvhobbs@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 <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)
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>             
>>>>>           
>>>       
>>     
>
>   


Mime
View raw message