Re: documentation

[Andrus Adamchik <an...@objectstyle.org>]

I just checked in the Ant task to generate the docs from Wiki. As we  
want to keep record of the docs version, and also since doc  
generation is a fairly expensive operation, I checked in the output  
to SVN under cayenne-other/wiki-docs.

To refresh the docs, run "ant doc" and commit the results. The beauty  
of it is that such procedure only checks in the changes made since  
last check in (so if Wiki hasn't changed, SVN won't change either).  
This way we can have real docs versioning. Of course a change in the  
Velocity template would result in all pages being updated, but this  
doesn't concern me at all.

TODOs:

* Do we have chapter ordering working?
* Link generated pages to the local JavaDocs, not the docs on the site.
* Should we move the content of "Documentation" folder one level up,  
so that it is at the same level as JavaDocs and other doc-related  
stuff in the release bundle? Cris, what do you think?

Andrus



On Apr 17, 2006, at 9:38 PM, Cris Daniluk wrote:

> I just checked in the code to generate the docs. I have not tied in  
> the ant
> task yet, as it does add considerable weight to the build time -  
> about 2
> minutes on my high speed connection. Basically, it would run  
> something like
> this:
>
>         <docgen spaceKey="CAYDOC" docBase="${doc.base}"
> startPage="Documentation" username="${confluenceUser.username}"  
> password="${
> confluenceUser.password}" />
>         <copy todir="${doc.base}">
>             <fileset dir="../cayenne-other/docs">
>                 <include name="**/*"/>
>             </fileset>
>         </copy>
>
>
> This will include the CSS and supporting images. The rest is fed  
> through a
> velocity template, and the content is pulled via the SOAP API. All
> attachments (aka images) are pulled locally and included in the doc  
> bundle,
> which seems to weigh in at around 2mb, not much larger than the old  
> docs
> when you consider what we've added in terms of new content. Note  
> that a
> confluence user/pass is required.
>
> I THINK the generated content is now correct. I've tested all the  
> links,
> etc. Feedback on this is definitely appreciated! Hopefully we can  
> have this
> all in place for the first milestone.
>
> Cris

Re: documentation

[Cris Daniluk <cr...@gmail.com>]

> TODOs:
>
> * Do we have chapter ordering working?

Actually, yes... though I haven't put it in everywhere. If you check
the source to the User Documentation page, you'll see an excerpt that
defines the ordering. It's a bit of a kludge, but Confluence's support
for this feature is a long way off. Till then, this is working peachy.
I will work to roll it out to the rest of the pages (it only needs to
be added to pages that have children)

> * Link generated pages to the local JavaDocs, not the docs on the site.

This is something that concerns me. I'm thinking that we should create
a macro for our javadoc refs. I think:

{cite}DataContext{cite}

Which would generate a link to the javadoc location specified somehow.
How is kind of important, but likewise kind of tricky. I don't think
there's a good way to attach custom metadata to pages, but maybe we
can do something similar to the excerpt hack where we place a hidden
reference to the javadoc location that corresponds to this "version"
of the docs. Hell, I guess it doesn't need to be a hidden link... we
could just make it a flat out link on the root of the Doc pages (for
general user reference). Either way, this will ensure that we generate
javadoc links to the appropriate version, and allow us a hook to
override for the local copies.

> * Should we move the content of "Documentation" folder one level up,
> so that it is at the same level as JavaDocs and other doc-related
> stuff in the release bundle? Cris, what do you think?

The only problem I had with this was that it meant the images, etc
needed to be at the same level as the javadoc. It's no big deal, but
kind of funny looking. If nobody else minds, I sure don't.

Cris