Making sandbox documentation available on our website

[Marshall Schor <ms...@schor.com>]

I plan to make a modification to the web-site to host all the sandbox
documentation, similar to how we host the base UIMA documentation.  Any
objections?

In preparation for this I'll be updating the builds for the sandbox
documentation to update a directory in the uima-website project.  I plan
to add a directory named
uima-website/docs/downloads/next-release/sandbox/<artifactId>.

After the release is approved, we can move the stuff in next-release to
the current place: uima-website/docs/downloads/sandbox/<artifactId>.

The website will only host the "current" release.  People wanting older
ones, can always download the distribution.

-Marshall

Re: Making sandbox documentation available on our website

[Tommaso Teofili <to...@gmail.com>]

I think that's a very nice idea.
+1

2009/9/21 Marshall Schor <ms...@schor.com>

> I plan to make a modification to the web-site to host all the sandbox
> documentation, similar to how we host the base UIMA documentation.  Any
> objections?
>
> In preparation for this I'll be updating the builds for the sandbox
> documentation to update a directory in the uima-website project.  I plan
> to add a directory named
> uima-website/docs/downloads/next-release/sandbox/<artifactId>.
>
> After the release is approved, we can move the stuff in next-release to
> the current place: uima-website/docs/downloads/sandbox/<artifactId>.
>
> The website will only host the "current" release.  People wanting older
> ones, can always download the distribution.
>
> -Marshall
>

Re: Making sandbox documentation available on our website

[Thilo Goetz <tw...@gmx.de>]

Michael Baessler wrote:
> Some time ago we discussed another way to access the current "trunk" version of the documentation.
> For some projects this was already enabled, but it seems that it never works :-(
> 
> We agreed to check-in the current pdf version of the documentation for a component and link this
> file directly in the Sandbox description. This was done for example for the RegexAnnotator,
> DictionaryAnnotator, SimpleServer, ...
> 
> Not sure if we need both ways, I don't think so. So I'm fine with Marshall's suggestion but in that
> case we should remove the old links that for some reasons are broken for some components.
> 
> -- Michael
> 
> Marshall Schor wrote:
>> I plan to make a modification to the web-site to host all the sandbox
>> documentation, similar to how we host the base UIMA documentation.  Any
>> objections?
>>
>> In preparation for this I'll be updating the builds for the sandbox
>> documentation to update a directory in the uima-website project.  I plan
>> to add a directory named
>> uima-website/docs/downloads/next-release/sandbox/<artifactId>.
>>
>> After the release is approved, we can move the stuff in next-release to
>> the current place: uima-website/docs/downloads/sandbox/<artifactId>.
>>
>> The website will only host the "current" release.  People wanting older
>> ones, can always download the distribution.
>>
>> -Marshall

+1 to Marshall's plan in principle.  I think one reason
we created this special sandbox documentation that Michael
refers to is that we have sandbox projects that have not
seen a release yet; but we still want people to be able
to get to the documentation so we can possibly get early
adopters and feedback.  What's your thought on that issue?
Create a subsection for non-released sandbox artifacts,
where we follow the "link to checked in docs" procedure
that Michael is alluding to?

--Thilo

Re: Making sandbox documentation available on our website

[Marshall Schor <ms...@schor.com>]

Michael Baessler wrote:
> Some time ago we discussed another way to access the current "trunk" version of the documentation.
> For some projects this was already enabled, but it seems that it never works :-(
> We agreed to check-in the current pdf version of the documentation for a component and link this
> file directly in the Sandbox description. This was done for example for the RegexAnnotator,
> DictionaryAnnotator, SimpleServer, ...
>   
Thanks, I had merely forgotten that.  I had been going thru the Sandbox
builds, and making them all the same (mostly via factoring things into
one place in the build, usually a parent POM), and had adopted the
practice of not storing the generated docs in the SVN of the project
(because they were "generated" :-) )...  I did not remember discussing
this, nor the previous decisions about this.

So we have two approaches:  putting these generated files in the
project's SVN, and linking to them from the web-site, or putting the
generated files on the web-site's SVN, and linking them from there.  I
am slightly in favor of leaving them as we had them before, in the
project's SVN, and getting the web-site to work. 

One difference - the web-site should link to the TAG for the release,
not to trunk, I think.  I suspect the reasons these links are not
currently working is because the doc/ directory was never put into the
TAG for the release, previously, and these directories are curently not
in the TRUNK branch, due to my changing how this was all being done for
the 2.3.0 release (which I'll now undo and go back to the previous method).

I'll also add a note in the common build step that documents why we're
saving the generated output, for future maintainers.

Thanks, again, Michael, for reminding me of these details :-)

-Marshall
> Not sure if we need both ways, I don't think so. So I'm fine with Marshall's suggestion but in that
> case we should remove the old links that for some reasons are broken for some components.
>
> -- Michael
>
> Marshall Schor wrote:
>   
>> I plan to make a modification to the web-site to host all the sandbox
>> documentation, similar to how we host the base UIMA documentation.  Any
>> objections?
>>
>> In preparation for this I'll be updating the builds for the sandbox
>> documentation to update a directory in the uima-website project.  I plan
>> to add a directory named
>> uima-website/docs/downloads/next-release/sandbox/<artifactId>.
>>
>> After the release is approved, we can move the stuff in next-release to
>> the current place: uima-website/docs/downloads/sandbox/<artifactId>.
>>
>> The website will only host the "current" release.  People wanting older
>> ones, can always download the distribution.
>>
>> -Marshall
>>     
>
>
>
>   

Re: Making sandbox documentation available on our website

[Michael Baessler <mb...@michael-baessler.de>]

Some time ago we discussed another way to access the current "trunk" version of the documentation.
For some projects this was already enabled, but it seems that it never works :-(

We agreed to check-in the current pdf version of the documentation for a component and link this
file directly in the Sandbox description. This was done for example for the RegexAnnotator,
DictionaryAnnotator, SimpleServer, ...

Not sure if we need both ways, I don't think so. So I'm fine with Marshall's suggestion but in that
case we should remove the old links that for some reasons are broken for some components.

-- Michael

Marshall Schor wrote:
> I plan to make a modification to the web-site to host all the sandbox
> documentation, similar to how we host the base UIMA documentation.  Any
> objections?
> 
> In preparation for this I'll be updating the builds for the sandbox
> documentation to update a directory in the uima-website project.  I plan
> to add a directory named
> uima-website/docs/downloads/next-release/sandbox/<artifactId>.
> 
> After the release is approved, we can move the stuff in next-release to
> the current place: uima-website/docs/downloads/sandbox/<artifactId>.
> 
> The website will only host the "current" release.  People wanting older
> ones, can always download the distribution.
> 
> -Marshall