You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cayenne.apache.org by Cris Daniluk <cr...@gmail.com> on 2006/04/18 03:38:12 UTC
documentation
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
Posted by Andrus Adamchik <an...@objectstyle.org>.
Yeah, this was build path related. PDF stuff is in a different source
folder and is built from another Ant file (doc.xml) with itext lib
included via a different path. I just fixed the build paths to
include everything from the cayenne-other/lib folder whenever the
tools are built. The build should work now.
Andrus
On Apr 19, 2006, at 3:09 AM, Cris Daniluk wrote:
> I'm a bit confused by this... the confluence-soap.jar is checked in
> and
> contains the necessary dependencies. It looks like the ant task isn't
> including the jar under cayenne-other/lib... however, the PDF tools
> are also
> in the cayenne-other/src tree and rely on itext.jar, which is in
> the lib
> folder
>
> Any thoughts?
>
> Cris
>
> On 4/18/06, Cris Daniluk <cr...@gmail.com> wrote:
>>
>> I bundled the wsdl2java-generated code into a JAR file - looks
>> like it
>> didn't get committed, though I'm not sure why it didn't show up in
>> the sync.
>> I will commit it as soon as I'm home.
>>
>> Sorry!
>>
>> Cris
>>
>>
>> On 4/18/06, Andrus Adamchik <an...@objectstyle.org> wrote:
>>>
>>> Cris,
>>>
>>> I am getting a bunch of errors like the one below when I do "cd
>>> cayenne-ant && ant". Is there some generated code that needs to be
>>> checked in?
>>>
>>>
>>> [mkdir] Created dir: /Volumes/hfs2/Users/andrus/work/cayenne/
>>> cayenne-ant/build/tools/classes
>>> [javac] Compiling 5 source files to /Volumes/hfs2/Users/andrus/
>>> work/cayenne/cayenne-ant/build/tools/classes
>>> [javac] /Volumes/hfs2/Users/andrus/work/cayenne/cayenne-other/
>>> src/tools/java/org/objectstyle/cayenne/tools/ant/docgen/
>>> DocGenerator.java:63: package
>>> org.objectstyle.confluence.rpc.soap_axis.confluenceservice_v1 does
>>> not exist
>>> [javac] import
>>> org.objectstyle.confluence.rpc.soap_axis.confluenceservice_v1.Conflu
>>> ence
>>> SoapService;
>>>
>>> [javac]
>>> ^
>>> [javac] /Volumes/hfs2/Users/andrus/work/cayenne/cayenne-other/
>>> src/tools/java/org/objectstyle/cayenne/tools/ant/docgen/
>>> DocGenerator.java:64: package
>>> org.objectstyle.confluence.rpc.soap_axis.confluenceservice_v1 does
>>> not exist
>>> [javac] import
>>> org.objectstyle.confluence.rpc.soap_axis.confluenceservice_v1.Conflu
>>> ence
>>> SoapServiceProxy;
>>>
>>>
>>> Andrus
>>>
>>> On Apr 18, 2006, at 5:38 AM, 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
Posted by Cris Daniluk <cr...@gmail.com>.
I'm a bit confused by this... the confluence-soap.jar is checked in and
contains the necessary dependencies. It looks like the ant task isn't
including the jar under cayenne-other/lib... however, the PDF tools are also
in the cayenne-other/src tree and rely on itext.jar, which is in the lib
folder
Any thoughts?
Cris
On 4/18/06, Cris Daniluk <cr...@gmail.com> wrote:
>
> I bundled the wsdl2java-generated code into a JAR file - looks like it
> didn't get committed, though I'm not sure why it didn't show up in the sync.
> I will commit it as soon as I'm home.
>
> Sorry!
>
> Cris
>
>
> On 4/18/06, Andrus Adamchik <an...@objectstyle.org> wrote:
> >
> > Cris,
> >
> > I am getting a bunch of errors like the one below when I do "cd
> > cayenne-ant && ant". Is there some generated code that needs to be
> > checked in?
> >
> >
> > [mkdir] Created dir: /Volumes/hfs2/Users/andrus/work/cayenne/
> > cayenne-ant/build/tools/classes
> > [javac] Compiling 5 source files to /Volumes/hfs2/Users/andrus/
> > work/cayenne/cayenne-ant/build/tools/classes
> > [javac] /Volumes/hfs2/Users/andrus/work/cayenne/cayenne-other/
> > src/tools/java/org/objectstyle/cayenne/tools/ant/docgen/
> > DocGenerator.java:63: package
> > org.objectstyle.confluence.rpc.soap_axis.confluenceservice_v1 does
> > not exist
> > [javac] import
> > org.objectstyle.confluence.rpc.soap_axis.confluenceservice_v1.Confluence
> > SoapService;
> >
> > [javac]
> > ^
> > [javac] /Volumes/hfs2/Users/andrus/work/cayenne/cayenne-other/
> > src/tools/java/org/objectstyle/cayenne/tools/ant/docgen/
> > DocGenerator.java:64: package
> > org.objectstyle.confluence.rpc.soap_axis.confluenceservice_v1 does
> > not exist
> > [javac] import
> > org.objectstyle.confluence.rpc.soap_axis.confluenceservice_v1.Confluence
> > SoapServiceProxy;
> >
> >
> > Andrus
> >
> > On Apr 18, 2006, at 5:38 AM, 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
Posted by Cris Daniluk <cr...@gmail.com>.
I bundled the wsdl2java-generated code into a JAR file - looks like it
didn't get committed, though I'm not sure why it didn't show up in the sync.
I will commit it as soon as I'm home.
Sorry!
Cris
On 4/18/06, Andrus Adamchik <an...@objectstyle.org> wrote:
>
> Cris,
>
> I am getting a bunch of errors like the one below when I do "cd
> cayenne-ant && ant". Is there some generated code that needs to be
> checked in?
>
>
> [mkdir] Created dir: /Volumes/hfs2/Users/andrus/work/cayenne/
> cayenne-ant/build/tools/classes
> [javac] Compiling 5 source files to /Volumes/hfs2/Users/andrus/
> work/cayenne/cayenne-ant/build/tools/classes
> [javac] /Volumes/hfs2/Users/andrus/work/cayenne/cayenne-other/
> src/tools/java/org/objectstyle/cayenne/tools/ant/docgen/
> DocGenerator.java:63: package
> org.objectstyle.confluence.rpc.soap_axis.confluenceservice_v1 does
> not exist
> [javac] import
> org.objectstyle.confluence.rpc.soap_axis.confluenceservice_v1.Confluence
> SoapService;
>
> [javac]
> ^
> [javac] /Volumes/hfs2/Users/andrus/work/cayenne/cayenne-other/
> src/tools/java/org/objectstyle/cayenne/tools/ant/docgen/
> DocGenerator.java:64: package
> org.objectstyle.confluence.rpc.soap_axis.confluenceservice_v1 does
> not exist
> [javac] import
> org.objectstyle.confluence.rpc.soap_axis.confluenceservice_v1.Confluence
> SoapServiceProxy;
>
>
> Andrus
>
> On Apr 18, 2006, at 5:38 AM, 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
Posted by Andrus Adamchik <an...@objectstyle.org>.
Cris,
I am getting a bunch of errors like the one below when I do "cd
cayenne-ant && ant". Is there some generated code that needs to be
checked in?
[mkdir] Created dir: /Volumes/hfs2/Users/andrus/work/cayenne/
cayenne-ant/build/tools/classes
[javac] Compiling 5 source files to /Volumes/hfs2/Users/andrus/
work/cayenne/cayenne-ant/build/tools/classes
[javac] /Volumes/hfs2/Users/andrus/work/cayenne/cayenne-other/
src/tools/java/org/objectstyle/cayenne/tools/ant/docgen/
DocGenerator.java:63: package
org.objectstyle.confluence.rpc.soap_axis.confluenceservice_v1 does
not exist
[javac] import
org.objectstyle.confluence.rpc.soap_axis.confluenceservice_v1.Confluence
SoapService;
[javac]
^
[javac] /Volumes/hfs2/Users/andrus/work/cayenne/cayenne-other/
src/tools/java/org/objectstyle/cayenne/tools/ant/docgen/
DocGenerator.java:64: package
org.objectstyle.confluence.rpc.soap_axis.confluenceservice_v1 does
not exist
[javac] import
org.objectstyle.confluence.rpc.soap_axis.confluenceservice_v1.Confluence
SoapServiceProxy;
Andrus
On Apr 18, 2006, at 5:38 AM, 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
Posted by 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
Re: documentation
Posted by 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
Posted by Andrus Adamchik <an...@objectstyle.org>.
On Apr 18, 2006, at 5:38 AM, Cris Daniluk wrote:
> 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>
We can separate the doc generation procedure from the rest of ant tasks:
* kill current doc sources in CVS
* rewrite current "doc" target to use docgen
* remove "doc" target from other target dependencies
So whoever builds a release will need to rebuild the docs manually.
Andrus