jGrouseDoc 2.0beta

[denis.r...@gmail.com]

Hi,

I think there are sufficient changes to justify the release of
jGrouseDoc 2.0beta.
I am publishing the file here in Groups, see
http://my.yahoo.com/http://groups.google.com/group/jgrousedoc/web/jGrouseDoc-2.0beta.zip

The most notable changes are:
- Support for new renderer based on Velocity templates - it is
lightning fast!
- Support for parsing "next ID"

Please try out the new version and let me know if you find any
problems with it. if no problems reported, I will make an official
release in a week or two.

Best regards,
Denis

[Broofa]

Denis, I just got the new v2.0 working and *DAMN* the performance
improvements are staggering! The documentation that used to take 12-13
minutes to generate now renders in 11 seconds. You (and Velocity)
rock!

Hey, any chance I can talk you into making the logo that displays at
the top of the noframes skin configurable? It looks like our project
logo is the jGD logo (which, nice as it is, isn't really what I want).

For jGD branding, I'd recommend that you add a simple (and subtle)
"powered by jGD" link + logo at the bottom of the page. Something
like JSDoc toolkit does ... http://code.google.com/apis/gadgets/docs/reference/gadgets.json.html

On Mar 10, 4:06 am, denis.riabtc...@gmail.com wrote:
> Hi,
>
> I think there are sufficient changes to justify the release of
> jGrouseDoc 2.0beta.

> I am publishing the file here in Groups, seehttp://my.yahoo.com/http://groups.google.com/group/jgrousedoc/web/jGr...

[denis.r...@gmail.com]

Hey, great that it works for you!

I never had an intent to force people to use jGrouseDoc logo - the one
coming in the distribution is merely a placeholder.
I would even consider putting something like "replace with your logo"
on top of it (actually, I think it's necessary to do it in order to
avoid confusion).

The logo is being inserted by CSS as a background image and thus it
should be quite easy to change it.
The simplest way is to copy your own logo into the output directory
and call it "logo.gif" after you invoke jGrouseDoc build.
Or provide your own css with override of ".banner h1 a"
Third option is if you would want to go wild and create your own theme
- that would give you full power.

Do you think that would be sufficient? I'd rather not jam into
jGrouseDoc functionality that does not really belong in there, like
copying user's files.

Regarding marketing - it is necessary to put a bit more thought in it.
My current thinking is some kind of build option that would turn that
line on.

Regards,
Denis

On Mar 10, 9:50 pm, Broofa <bro...@gmail.com> wrote:
> Denis, I just got the new v2.0 working and *DAMN* the performance
> improvements are staggering! The documentation that used to take 12-13
> minutes to generate now renders in 11 seconds. You (and Velocity)
> rock!
>
> Hey, any chance I can talk you into making the logo that displays at
> the top of the noframes skin configurable? It looks like our project
> logo is the jGD logo (which, nice as it is, isn't really what I want).
>
> For jGD branding, I'd recommend that you add a simple (and subtle)
> "powered by jGD" link + logo at the bottom of the page. Something

> like JSDoc toolkit does ...http://code.google.com/apis/gadgets/docs/reference/gadgets.json.html

[Broofa]

I see your point. The only problem I see is that with that jGD logo
at the top, *everyone* is going to want to change it or remove it. So
either jGD needs to make changing it easy (easier than configuring /
creating a custom CSS file, which is more trouble than it's worth for
most users) or just get rid of it altogether.

BTW, note that customizing template files has a similar issue as
customizing the configuration. Keeping template files sync'ed across
versions can be a bit of a chore. I think it makes sense to have
certain common properties configurable in the jgrousedoc.properties
file. (E.g. One could argue that the Logo is just a visual form of
the project name - which can be configured in the properties file).

[denis.r...@gmail.com]

I'm a bit lost here.
What could be easier than copying file over the default one?
I guess that's exactly what you're doing, right?
I would even put it into manual into the "install/config" section.
Also it is possible to ship "blank" logo file for those who don't want
to have any logos on the screen.

Customization of configuration from version to version is damn simple
now - just keep what you have and if you need to change the default
behavior then add the necessary lines. The only parameters that must
be overridden are jGrouseHome directory and locations of input/output
files.

BTW, how are you customizing the templates? I strongly suspect that
with Velocity there is a new way to do it without modifications of
standard files

Regards,
Denis

[Broofa]

> What could be easier than copying file over the default one?

I'm sorry, I'm not sure which file you're referring to? The logo.gif
file? The one in the jGD package gets overwritten each time I upgrade
to a new version of jGD. The one in the generated api directory is
overwritten each time I generate docs. jgdoc.css has the same
problem. The only way to permanently change the logo is to create a
custom CSS file and edit the aux_css property in
jgrousedoc.properties.

But that is not what I would describe as "trivially easy" - there are
several little pitfalls in doing this:
- Where do I put my aux_css file?
- What path do I use for aux_css? (e.g is it relative to the directory
I run jgd in? or the generated api directory? or ${jGrouseHome}?)
- What selector do I override?
- How do I set the width/height of the image? (padding-right and line-
height are not exactly the most intuitive attributes for this)

All new users are going to have to edit the jgrousedoc.properties file
_anyway_, so if we can do this without taking them out of that
experience, I think it is much simpler. For example, if there

# Path to the project logo. This is will be relative to the
generated /api
# directory. Some examples:
# logoUrl=../my_project/images/my_logo.gif
# logoUrl=/some_dir/my_logo.gif
# logoUrl=http://mysite.com/my_logo.gif
logoUrl=logo.gif

Please note that I go into detail on this mostly to demonstrate what I
think is a fundamental difference in our perception of what an "easy
and acceptable" new user experience is. I am perfectly fine with just
removing the logo altogether and avoiding this whole issue for now.
But I believe having it in there necessitates solving this problem
properly.

> I guess that's exactly what you're doing, right?
> I would even put it into manual into the "install/config" section.
> Also it is possible to ship "blank" logo file for those who don't want
> to have any logos on the screen.

This just seems like overkill for what (from a user's perspective)
should be a simple configuration property.

> Customization of configuration from version to version is damn simple
> now - just keep what you have and if you need to change the default
> behavior then add the necessary lines. The only parameters that must
> be overridden are jGrouseHome directory and locations of input/output
> files.

Yes and no. Customization has gotten better, but I'm still having to
"merge" jgrousedoc.properties configuration files with each new
version. I'll follow up with a separate post about this.

> BTW, how are you customizing the templates? I strongly suspect that
> with Velocity there is a new way to do it without modifications of
> standard files

I'm not. Not yet at least. :)

[denis.r...@gmail.com]

Hey, hey, why make things more complicated then they should be?
You're rising valid points, but I guess the right answer to them is
proper documentation, which is my objective for the next couple of
weeks.

No need to modify the original jGrouseDoc files.
I guess you have a build script that invokes jGrouseDoc.
In your build script simply copy your own logo file into the output
directory and name it logo.gif
For simplicity, the size of your logo should be comparable to the
standard one.

The aux_css is even simpler. The value of the property is the location
of your additional css file relative to your output directory (but for
obvious reasons it must be reachable via web if you are deploying your
docs on a server).

I am more than happy to help with all the issues regarding
customization of the output and your questions are highlighting the
areas that should receive more attention in the docs.

jGrouseDoc is good (I hope) in two things:
1. Parsing source files
2. Rendering output content

From my perspective, the criterion for decision whether to add a new
option to jGrouseDoc or not is simple - if the required result could
be achieved in a simple way outside of jGrouseDoc (like file copy),
then it should be done outside. If it is something less trivial, for
example, that affects output, then it could be added to the tool as a
new feature.

I don't think it's a good idea to drop the logo. First of all, I like
the layout :-)
Second, if it is removed, then most users simply won't know that it is
possible to add their logo over there.

This is how I see it now. Of course, if there would be more requests
to drop the logo for good or requests to provide the configuration for
logo right in jGrouseDoc, then we can return to this discussion. Only
fools and dead never change their opinion :-)

Regards,
Denis