site suggestion

classic Classic list List threaded Threaded
17 messages Options
Reply | Threaded
Open this post in threaded view
|

site suggestion

Ittay Dror
Did you guys think of structuring the documentation section like vim.sf.net or mysql's site? In both of them, users can add comments to the documentation page. These comments usually have a wealth of information in them.

Related to that, why the separation of wiki and documents? A wiki with the documents and with an ability for adding comments at the buttom, will be excellent.

Ittay
Reply | Threaded
Open this post in threaded view
|

Re: site suggestion

hans_d
Administrator

On May 29, 2008, at 8:31 AM, Ittay Dror wrote:

>
> Did you guys think of structuring the documentation section like  
> vim.sf.net
> or mysql's site? In both of them, users can add comments to the
> documentation page. These comments usually have a wealth of  
> information in
> them.
>
> Related to that, why the separation of wiki and documents? A wiki  
> with the
> documents and with an ability for adding comments at the buttom,  
> will be
> excellent.

I definitely see the positive side of such an approach. Yet there are  
a couple of reasons why we don't do this.

- I like to have a PDF version of the documentation (e.g. for nice  
searching). We are hosted at codehaus which provides us the  
confluence wiki. Confluence does not preserve the order when  
exporting to PDF. The chapters in your PDF are always alphabetically  
sorted. The confluence guys are working on this, but I don't know  
when this is released and when codehaus updates to this new version  
of confluence.
- I don't know about the other wikis. What I think is essential for a  
robust documentation is automatic generation of chapter, section and  
subsection numbers. Also the possibility to create links to labels,  
so that you don't have to worry about fixing the references when you  
add sections to it. Sooner or later we will also create and index for  
our documentation.
- The layout of Latex is very nice.
- Most of the code snippets in the documentation are integration  
tests. We automatically include the source code of the tests into the  
documentation. When we execute the tests we capture the output and  
include this output also in the documentation. I wouldn't know now to  
do this with confluence.

One possible way of combining both approaches would be to export the  
generated documentation into a wiki.

- Hans

>
> Ittay
> --
> View this message in context: http://www.nabble.com/site-suggestion- 
> tp17528465p17528465.html
> Sent from the gradle-dev mailing list archive at Nabble.com.
>
>
> ---------------------------------------------------------------------
> To unsubscribe from this list, please visit:
>
>     http://xircles.codehaus.org/manage_email
>
>

--
Hans Dockter
Gradle Project lead
http://www.gradle.org





---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|

Re: site suggestion

Ittay Dror

hdockter wrote
One possible way of combining both approaches would be to export the  
generated documentation into a wiki.
Maybe another approach is for the users to access the manual's html pages through a php script that will show to manual page and add a list of comments
Reply | Threaded
Open this post in threaded view
|

Re: site suggestion

hans_d
Administrator

On May 29, 2008, at 1:54 PM, Ittay Dror wrote:

>
>
>
> hdockter wrote:
>>
>> One possible way of combining both approaches would be to export the
>> generated documentation into a wiki.
>>
> Maybe another approach is for the users to access the manual's html  
> pages
> through a php script that will show to manual page and add a list of
> comments

This is a good idea. I'd love to get direct feedback on the docu. Any  
ambitions to give this a go ? :)

The only drawback right now is that the html documentation is pretty  
ugly and not so easy to read than the pdf one. We have to learn more  
about the latex2html generation to improve this.

- Hans

> --
> View this message in context: http://www.nabble.com/site-suggestion- 
> tp17528465p17534015.html
> Sent from the gradle-dev mailing list archive at Nabble.com.
>
>
> ---------------------------------------------------------------------
> To unsubscribe from this list, please visit:
>
>     http://xircles.codehaus.org/manage_email
>
>

--
Hans Dockter
Gradle Project lead
http://www.gradle.org





---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|

Re: site suggestion

Ittay Dror

hdockter wrote
This is a good idea. I'd love to get direct feedback on the docu. Any  
ambitions to give this a go ? :)
I know nothing about PHP, but sure, why not ;)

Does codehaus let you run PHP and MySQL?

Ittay
Reply | Threaded
Open this post in threaded view
|

Re: site suggestion

Ittay Dror
In reply to this post by hans_d

hdockter wrote
This is a good idea. I'd love to get direct feedback on the docu. Any  
ambitions to give this a go ? :)
I know nothing about PHP, but sure, why not ;)

Does codehaus let you run PHP and MySQL?

Ittay
Reply | Threaded
Open this post in threaded view
|

Re: site suggestion

Ittay Dror
In reply to this post by hans_d

hdockter wrote
This is a good idea. I'd love to get direct feedback on the docu. Any  
ambitions to give this a go ? :)
I know nothing about PHP, but sure, why not ;)

Does codehaus let you run PHP and MySQL?

Ittay
Reply | Threaded
Open this post in threaded view
|

Re: site suggestion

Ittay Dror
In reply to this post by hans_d

hdockter wrote
This is a good idea. I'd love to get direct feedback on the docu. Any  
ambitions to give this a go ? :)
I know nothing about PHP, but sure, why not ;)

Does codehaus let you run PHP and MySQL?

Ittay
Reply | Threaded
Open this post in threaded view
|

Re: site suggestion

Ittay Dror
In reply to this post by hans_d

hdockter wrote
This is a good idea. I'd love to get direct feedback on the docu. Any  
ambitions to give this a go ? :)
I know nothing about PHP, but sure, why not ;)

Does codehaus let you run PHP and MySQL?

Ittay
Reply | Threaded
Open this post in threaded view
|

Re: site suggestion

Ittay Dror
In reply to this post by hans_d

hdockter wrote
This is a good idea. I'd love to get direct feedback on the docu. Any  
ambitions to give this a go ? :)
I know nothing about PHP, but sure, why not ;)

Does codehaus let you run PHP and MySQL?

Ittay
Reply | Threaded
Open this post in threaded view
|

Re: site suggestion

hans_d
Administrator
In reply to this post by Ittay Dror

On May 29, 2008, at 3:48 PM, Ittay Dror wrote:

>
>
>
> hdockter wrote:
>>
>> This is a good idea. I'd love to get direct feedback on the docu. Any
>> ambitions to give this a go ? :)
>>
>>
> I know nothing about PHP, but sure, why not ;)
>
> Does codehaus let you run PHP and MySQL?

The Gradle website is not hosted at codehaus as we have our own  
domain. The current host provides PHP and MySQL. Another option would  
be to check if Confluence has some REST API. Than we could upload the  
docu to our Wiki and could use the confluence comments functionality.

- Hans

>
> Ittay
> --
> View this message in context: http://www.nabble.com/site-suggestion- 
> tp17528465p17536180.html
> Sent from the gradle-dev mailing list archive at Nabble.com.
>
>
> ---------------------------------------------------------------------
> To unsubscribe from this list, please visit:
>
>     http://xircles.codehaus.org/manage_email
>
>

--
Hans Dockter
Gradle Project lead
http://www.gradle.org





---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|

Re: site suggestion

Ittay Dror
hdockter wrote
The Gradle website is not hosted at codehaus as we have our own  
domain. The current host provides PHP and MySQL. Another option would  
be to check if Confluence has some REST API. Than we could upload the  
docu to our Wiki and could use the confluence comments functionality.
does this help? http://stephane.nicoll.net/projects/maven-confluence-plugin/

it lets you post a single page to confluence. i can probably hack something that will allow to post a set of pages, but it means using maven...

ittay
Reply | Threaded
Open this post in threaded view
|

Re: site suggestion

hans_d
Administrator

On May 29, 2008, at 7:02 PM, Ittay Dror wrote:

>
>
> hdockter wrote:
>>
>> The Gradle website is not hosted at codehaus as we have our own
>> domain. The current host provides PHP and MySQL. Another option would
>> be to check if Confluence has some REST API. Than we could upload the
>> docu to our Wiki and could use the confluence comments functionality.
>>
> does this help? http://stephane.nicoll.net/projects/maven- 
> confluence-plugin/
>
> it lets you post a single page to confluence. i can probably hack  
> something
> that will allow to post a set of pages, but it means using maven...

Cool, it looks like Confluence is offering an API to our needs. I  
think we would not necessarily need to use Maven. The code is  
available as LGPL and as its not shipped with the Gradle Dist (which  
is Apache v2) this is fine for us. We could extract the parts we need.

What do you think?

- Hans


>
> ittay
>
> --
> View this message in context: http://www.nabble.com/site-suggestion- 
> tp17528465p17541019.html
> Sent from the gradle-dev mailing list archive at Nabble.com.
>
>
> ---------------------------------------------------------------------
> To unsubscribe from this list, please visit:
>
>     http://xircles.codehaus.org/manage_email
>
>

--
Hans Dockter
Gradle Project lead
http://www.gradle.org





---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|

Re: site suggestion

Ittay Dror
hdockter wrote
Cool, it looks like Confluence is offering an API to our needs. I  
think we would not necessarily need to use Maven. The code is  
available as LGPL and as its not shipped with the Gradle Dist (which  
is Apache v2) this is fine for us. We could extract the parts we need.

What do you think?
I think this is a good approach. I don't have authorization to the site, so I can't do it.

Ittay
Reply | Threaded
Open this post in threaded view
|

Re: site suggestion

hans_d
Administrator

On May 29, 2008, at 8:16 PM, Ittay Dror wrote:

>
>
> hdockter wrote:
>>
>> Cool, it looks like Confluence is offering an API to our needs. I
>> think we would not necessarily need to use Maven. The code is
>> available as LGPL and as its not shipped with the Gradle Dist (which
>> is Apache v2) this is fine for us. We could extract the parts we  
>> need.
>>
>> What do you think?
>>
> I think this is a good approach. I don't have authorization to the  
> site, so
> I can't do it.

I can assign authorization to you, this is no problem. You have to  
first sign up to the codehaus confluence:

http://docs.codehaus.org/signup.action

After this I can assign the permissions. I'm off very soon, so I  
might not be able to do this before Monday.

- Hans

>
> Ittay
> --
> View this message in context: http://www.nabble.com/site-suggestion- 
> tp17528465p17542551.html
> Sent from the gradle-dev mailing list archive at Nabble.com.
>
>
> ---------------------------------------------------------------------
> To unsubscribe from this list, please visit:
>
>     http://xircles.codehaus.org/manage_email
>
>

--
Hans Dockter
Gradle Project lead
http://www.gradle.org





---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|

Re: site suggestion

Ittay Dror

hdockter wrote
I can assign authorization to you, this is no problem. You have to  
first sign up to the codehaus confluence:
OK., thanks. My user id is ittayd

Also, the maven plugin I mentioned seems to be old and using APIs that are no longer supported. I found new APIs:
http://svn.atlassian.com/svn/public/contrib/confluence/confluence-rpc-plugin/trunk
(I have some doubts about using it, it may need enabling on the server side)

But then ran into this:
http://confluence.atlassian.com/display/CONFEXT/Confluence+Command+Line+Interface

It's a CLI that allows you to do remote actions on confluence, is it enough for your needs?

Ittay

Reply | Threaded
Open this post in threaded view
|

Re: site suggestion

hans_d
Administrator

On May 30, 2008, at 1:36 PM, Ittay Dror wrote:

>
>
>
> hdockter wrote:
>>
>> I can assign authorization to you, this is no problem. You have to
>> first sign up to the codehaus confluence:
>>
> OK., thanks. My user id is ittayd
>

It came to my mind that it probably makes more sense to have an  
distinct non real user which connects to our wiki and manipulates it.

I will send you a separate email with the details.

> Also, the maven plugin I mentioned seems to be old and using APIs  
> that are
> no longer supported. I found new APIs:
> http://svn.atlassian.com/svn/public/contrib/confluence/confluence- 
> rpc-plugin/trunk
> (I have some doubts about using it, it may need enabling on the  
> server side)
>
> But then ran into this:
> http://confluence.atlassian.com/display/CONFEXT/Confluence+Command 
> +Line+Interface
>
> It's a CLI that allows you to do remote actions on confluence, is  
> it enough
> for your needs?

This looks very promising. The only thing that we might need but is  
not offered at the moment is manipulating comments. But I guess this  
has to be usually done manually anyway. For example if a comment has  
become obsolete after an documentation update.

- Hans

>
> Ittay
>
>
> --
> View this message in context: http://www.nabble.com/site-suggestion- 
> tp17528465p17556858.html
> Sent from the gradle-dev mailing list archive at Nabble.com.
>
>
> ---------------------------------------------------------------------
> To unsubscribe from this list, please visit:
>
>     http://xircles.codehaus.org/manage_email
>
>

--
Hans Dockter
Gradle Project lead
http://www.gradle.org





---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email