Documentation

[kirk24788]

There was a question on the PG forums where the new features are explained...
And I think it'S time for some documentation - not only the new stuff but also the old stuff...
I was thinking a python script might do the trick - parsing documentation comments and generating a html page on demand...
I looked at luadoc...but installing it is way more complicated than just executing a simple python script (and python is installed on all macs).

I already started coding, will publish some results this weekend

[ghost]

you're right :)

think before we going to do this we should clean up the code.
I'm start with this now :)

Am 19.07.2013 um 10:49 schrieb kirk24788 [email protected]:

There was a question on the PG forums where the new features are explained...
And I think it'S time for some documentation - not only the new stuff but also the old stuff...
I was thinking a python script might do the trick - parsing documentation comments and generating a html page on demand...
I looked at luadoc...but installing it is way more complicated than just executing a simple python script (and python is installed on all macs).

I already started coding, will publish some results this weekend

—
Reply to this email directly or view it on GitHub.

[kirk24788]

Yeah, cleanup would be nice...I started with a special test file for testing the script, but I've already at a stage where I want some real data. I'm starting with jpdots.lua - only two methods... :D
As soon as I have that finished I'll head over to the warlock destruction rotation (still have to make the rotation doc parser) and then I'll get try my luck with CSS.
As soon as that's done I'll commit a hopefully working document generator script...then the boring part starts...the actual documentation

[ghost]

okay :)

I'm going to replace spaces with tabs. Because it's easier to indent and we got less wrong indentations (currently some indent with 2 space, some with 4 and I also saw 3 spaces as indentation) Tab is Tab and their you CANT do anything wrong :) :D

(For a few month I was for spaces but now I see the con's of them)

Am 19.07.2013 um 11:23 schrieb kirk24788 [email protected]:

Yeah, cleanup would be nice...I started with a special test file for testing the script, but I've already at a stage where I want some real data. I'm starting with jpdots.lua - only two methods... :D
As soon as I have that finished I'll head over to the warlock destruction rotation (still have to make the rotation doc parser) and then I'll get try my luck with CSS.
As soon as that's done I'll commit a hopefully working document generator script...then the boring part starts...the actual documentation

—
Reply to this email directly or view it on GitHub.

[kirk24788]

Well I'm still agains tabs - you only have con's if you don't have a common identation - but on a open source projects its usually easier to use tabs....but please don't convert jpdots.lua and the warlock rotations - I'll do it as soon as the scripts finished

[ghost]

Yeah I was also against tabs (changed only for jps) because on open source it is really easier with tabs. 5 mins ago I saw a function mixed with tabs , 2 space, 3 space and 4 space indentation :) :D

I'm don't touch these files, no problem :)

Am 19.07.2013 um 12:01 schrieb kirk24788 [email protected]:

Well I'm still agains tabs - you only have con's if you don't have a common identation - but on a open source projects its usually easier to use tabs....but please don't convert jpdots.lua and the warlock rotations - I'll do it as soon as the scripts finished

—
Reply to this email directly or view it on GitHub.

[ghost]

awesome :) nice parser. tested a little bit with jpauras.lua. Easy handling but think we need to optimize the css a little bit for better readability:

• different modules / functions should be more splitted (background / border )
• serif-less fonts (arial,verdana)

all in all but very cool :) I personally would be happy if the html-tag brackets where normal > or < instead off [ and ], but this doesn't really matter. Would only increase editing speed :) :D

[ghost]

something like this:

--[[[
@module DoT Tracker
@description 
DoT Tracker for DoT-Classes. Currently only Destruction-Warlocks and Affliction-Warlocks are supported.
[br][br]
The DoT Tracker will track your DoT's on all valid units ([code]target[/code], [code]focus[/code], [code]mouseover[/code] and [code]boss1-4[/code]) and will tell you when to recast the spell.
If it is pandemic safe and you don't loose DPS your DoT's will always be re-applied. If it is not pandemic safe
the DoT will only be re-applied if you gain at least 225K DPS - based on 150K average DPS this should compensate
for the lost GCD. If you don't have the DoT on the target or there is only 2 seconds left it will be applied ignoring any DPS difference.
[br][br]
The DoT Tracker can be used with normal tables (#ref:jps.dotTracker.castTable) but since normal tables
are deprecated you should instead convert your rotation to a static spell table and use the appropriate
function (#ref:jps.dotTracker.castTableStatic).
]]]

crashes jps

it only works with:

--[[[
@module DoT Tracker
@description 
DoT Tracker for DoT-Classes. Currently only Destruction-Warlocks and Affliction-Warlocks are supported.
[br][br]
The DoT Tracker will track your DoT's on all valid units ([code]target[/code], [code]focus[/code], [code]mouseover[/code] and [code]boss1-4[/code]) and will tell you when to recast the spell.
If it is pandemic safe and you don't loose DPS your DoT's will always be re-applied. If it is not pandemic safe
the DoT will only be re-applied if you gain at least 225K DPS - based on 150K average DPS this should compensate
for the lost GCD. If you don't have the DoT on the target or there is only 2 seconds left it will be applied ignoring any DPS difference.
[br][br]
The DoT Tracker can be used with normal tables (#ref:jps.dotTracker.castTable) but since normal tables
are deprecated you should instead convert your rotation to a static spell table and use the appropriate
function (#ref:jps.dotTracker.castTableStatic).
]]--

but this crashes the doc :)

change is the last ]]]

[htordeux]

tested my priest today works fine nice cleaning code
if you want be perfect, in jpparse.. ^_^ write shield paladin
local divineshield = tostring(select(1,GetSpellInfo(642))) -- divine shild paladin

[ghost]

oh thx :) :D

[kirk24788]

changed ]]] to ]]--
Yeah, CSS needs some editing, only made it work, there's still plenty of room for optimization...especialy a TOC with jQuery would be nice.
And...you can code html directly - the [*] is only for those used to bb code...and yeah - I know it opens XSS holes...but that shouldn't be a problem here ;)

[ghost]

oh nice :) It is possible to implement jquery their ? Lol! :D

[kirk24788]

It's HTML...you only have to add jQuery to the index.html.in (which is the html template) and you're good to go ;)
BTW...the Documentation:

JPS Document Generator

The Document Generator will scan 4 different File Types,
the files are searched for comments beginning with --[[[ and end with ]]--
The comments are searched for tags (beginning with @), everything that follows a tag is counted towards it's content until the
next tag is found.
Invalid Tags or words preceeding the first tag are ignored.
The content can be plain HTML code or a limited number of BB Code Elements (for detailed information on which BB Code is supported,
you might want to look at the dictionary BB_CODE in the gendoc.py script).
Additional you can reference other functions with #ref:<function name>.


1. Modules
Everything needed for normal Rotation Editing - All file should be in the 'modules' directory.

The first comment is regarded as the module comment, supported Tags:
@module      - Name of the Module
@description - Extended Description of the Module

After the first comment all other comments are regarded as function comments, supported Tags:
@function    - Name of the function
@description - Extended Description of the function
@param       - Parameter, first word is the parameter name, the rest is the description of the parameter - this tag can occur 
                multiple times - one param for each parameter
@returns     - Description of the returned value
@deprecated  - Adds a warning to the documentation, that this function is deprecated. Any text after the tag is added to this warning

The Glob List is MODULE_GLOBS.


2. Advanced Functionality
More advanced functionality which isn't in the normal rotation but might be handy (e.g. adding your own events).
The Tags are the same as in Modules
The Glob List is ADVANCED_GLOBS.


3. Rotations
Description of the Rotations, all files in the 'Rotations' dir are scanned.
All comments are regarded as a Rotation, supported Tags:
@rotation     - Name of the rotation
@class        - Class-Name (english!)
@spec         - Full Spec Name (english!)
@deprecated   - Adds a warning to the documentation, that this rotation is deprecated, Any text after the tag is added to this warning
@description  - Extended Description of the rotation


The Glob List is ROTATION_GLOBS.


4. ToDo's
List of open ToDo's in the JPS source files. All lua files should be scanned.
All files are scanned for comments beginning with --JPTODO: - the preceding text is added as ToDo in the documentation.

Is already added in my github repository, will push it when I'm done with some more comments

[ghost]

I'm going to make today a small jQuery UI for the Documentation. With some accordions/tabs or stuff like that :)

[kirk24788]

Would be nice...it already is pretty big, and there's only a fraction documented...I guess I'll start documenting the rest of the files in the main directory or leave todo comments if I don't know what it does ;)

[jsmb768ypl]

So how does this work for the normal guy like me? because i i go to doc and in it are files but i don't know what some of them do and when i attempt to open the html.in file it doesn't load when i remove the .in it does but just the basic page you already copied here, so were would the doc's on the rotations be? Or is that what everyone is still working on?

[kirk24788]

the rotations aren't documented...except lock rotations....
you have to use the command line to enter the directory and type python gendoc.py
It will print out warnings (about the code which isn't yet documented) and generate a index.html - that's the file with the actual documentation (the index.html.in is only the template).

Maybe a script which just can be executed would be nice...

Does anyone know if github preserves file permissions?

[kirk24788]

Easier:
Create a file "Documentation.applescript" (well...only the extension is important)
with following contents:

set fullPath to (the POSIX path of (path to me))
set fileName to the name of (info for (path to me))
set fileDir to replaceText(fullPath, fileName, "")
do shell script ("cd " & fileDir & " && /usr/bin/python " & fileDir & "gendoc.py")
tell application "Finder"
    open file "index.html" of folder of (file (path to me))
end tell
to replaceText(someText, oldItem, newItem)
    (*
     replace all occurances of oldItem with newItem
          parameters -     someText [text]: the text containing the item(s) to change
                    oldItem [text, list of text]: the item to be replaced
                    newItem [text]: the item to replace with
          returns [text]:     the text with the item(s) replaced
     *)
    set {tempTID, AppleScript's text item delimiters} to {AppleScript's text item delimiters, oldItem}
    try
        set {itemList, AppleScript's text item delimiters} to {text items of someText, newItem}
        set {someText, AppleScript's text item delimiters} to {itemList as text, tempTID}
    on error errorMessage number errorNumber -- oops
        set AppleScript's text item delimiters to tempTID
        error errorMessage number errorNumber -- pass it on
    end try

    return someText
end replaceText

It opens in Script Editor - but can be executed....maybe we could add the compiled version to the doc dir....

[kirk24788]

Ok...it's easier to think in the morning.....added a Pull Request: #364
A simple App which generates the documentation and opens the index.html file