NS2Docs

Onos Ate MeOnos Ate Me Join Date: 2010-12-31 Member: 76072Members, NS2 Playtester, Squad Five Blue
edited February 2015 in Modding
<div class="IPBDescription">Documentation generator</div>Ns2Docs analyzes the lua code for Natural Selection 2 and produces code documentation similar to that of JavaDocs or LuaDoc

<!--sizeo:5--><span style="font-size:18pt;line-height:100%"><!--/sizeo--><a href="http://ns2docs.bplaced.net/" target="_blank">Generated Docs</a><!--sizec--></span><!--/sizec-->
<!--sizeo:4--><span style="font-size:14pt;line-height:100%"><!--/sizeo--><a href="http://dl.dropbox.com/u/53107776/ns2docs/Ns2Docs.zip" target="_blank">Download Ns2Docs</a><!--sizec--></span><!--/sizec-->
<!--sizeo:4--><span style="font-size:14pt;line-height:100%"><!--/sizeo--><a href="https://github.com/DamienHauta/Ns2Docs" target="_blank">GitHub</a><!--sizec--></span><!--/sizec-->

<!--sizeo:5--><span style="font-size:18pt;line-height:100%"><!--/sizeo-->System Requirements<!--sizec--></span><!--/sizec-->

<a href="http://www.microsoft.com/en-us/download/details.aspx?id=17851" target="_blank">Microsoft .NET Framework 4</a>

<!--sizeo:5--><span style="font-size:18pt;line-height:100%"><!--/sizeo-->Usage<!--sizec--></span><!--/sizec-->

<!--c1--><div class='codetop'>CODE</div><div class='codemain'><!--ec1-->Ns2Docs-Console.exe [-generator generator name] [-out output path] [source directories]<!--c2--></div><!--ec2-->

If no source directories are supplied, Ns2Docs will try to automatically find the Natural Selection installation directory by searching the registry.

<!--sizeo:5--><span style="font-size:18pt;line-height:100%"><!--/sizeo-->Sample Usage<!--sizec--></span><!--/sizec-->

<!--c1--><div class='codetop'>CODE</div><div class='codemain'><!--ec1-->Ns2Docs-Console.exe -generator Json -out "C:\Natural Selection 2\docs.json" "C:\Program Files (x86)\Steam\steamapps\common\natural selection 2" "c:\My Mod"<!--c2--></div><!--ec2-->
This will parse any files with names ending in .lua that are found in either <i>C:\Program Files (x86)\Steam\steamapps\common\natural selection 2</i> or <i>c:\My Mod</i>. The output will be a Json file that will gets written to <i>C:\Natural Selection 2\docs.json</i>.

<!--sizeo:4--><span style="font-size:14pt;line-height:100%"><!--/sizeo-->Generating Static Html Files<!--sizec--></span><!--/sizec-->

<!--c1--><div class='codetop'>CODE</div><div class='codemain'><!--ec1-->Ns2Docs-Console.exe<!--c2--></div><!--ec2-->

<!--sizeo:4--><span style="font-size:14pt;line-height:100%"><!--/sizeo-->Changing The Output Folder<!--sizec--></span><!--/sizec-->

<!--c1--><div class='codetop'>CODE</div><div class='codemain'><!--ec1-->Ns2Docs-Console.exe -out "C:\Natural Selection 2\docs"<!--c2--></div><!--ec2-->

The static html files will be written to <i>C:\Natural Selection 2\docs</i> instead of the default <i>ns2docs</i>.

<!--sizeo:4--><span style="font-size:14pt;line-height:100%"><!--/sizeo-->Generating Json Files<!--sizec--></span><!--/sizec-->

<!--c1--><div class='codetop'>CODE</div><div class='codemain'><!--ec1-->Ns2Docs-Console.exe -generator Json<!--c2--></div><!--ec2-->

<!--sizeo:4--><span style="font-size:14pt;line-height:100%"><!--/sizeo-->Changing The Output File<!--sizec--></span><!--/sizec-->

<!--c1--><div class='codetop'>CODE</div><div class='codemain'><!--ec1-->Ns2Docs-Console.exe -out "C:\Natural Selection 2\docs.json"<!--c2--></div><!--ec2-->

The Json file will be written to <i>C:\Natural Selection 2\docs.json</i> instead of <i>out.json</i>.

<!--sizeo:4--><span style="font-size:14pt;line-height:100%"><!--/sizeo-->Using Multiple Source Directories<!--sizec--></span><!--/sizec-->

<!--c1--><div class='codetop'>CODE</div><div class='codemain'><!--ec1-->Ns2Docs-Console.exe "C:\Program Files (x86)\Steam\steamapps\common\natural selection 2" "c:\My Mod"<!--c2--></div><!--ec2-->

<!--sizeo:4--><span style="font-size:14pt;line-height:100%"><!--/sizeo--><a href="http://dl.dropbox.com/u/53107776/ns2docs/Ns2Docs.zip" target="_blank">Download Ns2Docs</a><!--sizec--></span><!--/sizec-->
Off Topic Disagree Agree 1Awesome
«1

Comments

  • HarimauHarimau Join Date: 2007-12-24 Member: 63250Members
    edited January 2011
    Very nice. Just had a look through your website; if you look at Global Variables for instance, at ns2/lua/AlienStructureEffects.lua - the code isn't displaying properly. Could just be my browser though (IE7). Edit: Works fine in firefox. Seems like part of the code is missing though.
    Off Topic Disagree Agree Awesome
  • playerplayer Join Date: 2010-09-12 Member: 73982Members
    It works absolutely spiffingly, and indeed produced the most comprehensive overview of NS2's Lua-script to date. This is a keeper.

    <!--QuoteBegin-'Harimau'+--><div class='quotetop'>QUOTE ('Harimau')</div><div class='quotemain'><!--QuoteEBegin-->Very nice. Just had a look through your website; if you look at Global Variables for instance, at ns2/lua/AlienStructureEffects.lua - the code isn't displaying properly. Could just be my browser though (IE7). Edit: Works fine in firefox. Seems like part of the code is missing though.<!--QuoteEnd--></div><!--QuoteEEnd-->
    It appears to only display a maximum of around 10 lines of the definition, probably to maintain readability of the document. Just follow the "ns2/lua/AlienStructureEffects.lua:#"-link for a complete definition.
    Off Topic Disagree Agree Awesome
  • McGlaspieMcGlaspie www.team156.com Join Date: 2010-07-26 Member: 73044Members, Super Administrators, Forum Admins, NS2 Developer, NS2 Playtester, Squad Five Blue, Squad Five Silver, Squad Five Gold, Reinforced - Onos, WC 2013 - Gold, Subnautica Playtester
    This...is...awesome! Tyvm. Works like a charm.
    Off Topic Disagree Agree Awesome
  • Viper_two_nine_AViper_two_nine_A Join Date: 2004-09-29 Member: 31989Members
    edited January 2011
    cool! could you add some lua syntax highlighting to the source code viewer?

    update: nvm, had js disabled - great program!
    Off Topic Disagree Agree Awesome
  • KuBaNKuBaN Join Date: 2002-11-16 Member: 8979Members, Constellation
    I get this error when attempting: <!--c1--><div class='codetop'>CODE</div><div class='codemain'><!--ec1-->ns2docs.exe: ...Games\Natural Selection 2\ns2docs\lua\leg\parser.lua:182: attempt to call field 'Ca' (a nil value)<!--c2--></div><!--ec2-->

    The Demo was a great help and I hope to continue using this invaluable reference, so any advice on this would be appreciated.
    Off Topic Disagree Agree Awesome
  • ☼Lap☼☼Lap☼ Join Date: 2009-02-16 Member: 66432Members
    I get the same error. I can't even find a contact email to email the author.
    Off Topic Disagree Agree Awesome
  • Onos Ate MeOnos Ate Me Join Date: 2010-12-31 Member: 76072Members, NS2 Playtester, Squad Five Blue
    I fixed the bug and added a more user friendly error messages.
    <a href="http://damien.kodingen.com/ns2docs/ns2docs.zip" target="_blank">Download latest version</a>
    Turns out the bug was caused by the leg library raising an error while making an error message and class declarations being regarded as Lua keywords preventing code such as <i>local class = {}</i> from being parsed.

    <b>Note:</b> In build 184, the file <i>ns2/Build.lua</i> has a syntax error on line 21, <i>buildProgress = "float"</i> needs to end with a comma, preventing Ns2Docs from generating the documentation. Here is the fix for that:
    <!--c1--><div class='codetop'>CODE</div><div class='codemain'><!--ec1-->Build.networkVars =
    {    
        buildType           = "enum kTechType",
        buildTechId         = "integer",
        buildLocation       = "vector",
        buildOrientation    = "float",
        buildProgress       = "float",
        buildCompleted      = "boolean"
    }<!--c2--></div><!--ec2-->
    Off Topic Disagree Agree Awesome
  • ☼Lap☼☼Lap☼ Join Date: 2009-02-16 Member: 66432Members
    Writing doc/classes/index.html
    DocVariable.lua:49 attempt t index local 'assignment' (a nil value).

    I'm only getting this with files I've modified and not the base NS2. I don't know how to go about finding which variable, or even which file is causing this and why.

    Any theories on why or ways I can figure out where the problem is?
    Off Topic Disagree Agree Awesome
  • Onos Ate MeOnos Ate Me Join Date: 2010-12-31 Member: 76072Members, NS2 Playtester, Squad Five Blue
    <!--quoteo(post=1870358:date=Aug 21 2011, 07:43 AM:name=☼Lap☼)--><div class='quotetop'>QUOTE (☼Lap☼ @ Aug 21 2011, 07:43 AM) <a href="index.php?act=findpost&pid=1870358"><{POST_SNAPBACK}></a></div><div class='quotemain'><!--quotec-->Writing doc/classes/index.html
    DocVariable.lua:49 attempt t index local 'assignment' (a nil value).

    I'm only getting this with files I've modified and not the base NS2. I don't know how to go about finding which variable, or even which file is causing this and why.

    Any theories on why or ways I can figure out where the problem is?<!--QuoteEnd--></div><!--QuoteEEnd-->

    It seems that variable assignments are being parsed with no right hand value, I tried to replicate this problem but couldn't. I've updated ns2docs to print the file location and line number of the assignment being parsed when the assignment is <i>nil</i>. This fix will help you pin-point the problem at least.

    <a href="http://damien.kodingen.com/ns2docs/ns2docs-3.zip" target="_blank">NSDocs Build 3</a>
    Off Topic Disagree Agree Awesome
  • ☼Lap☼☼Lap☼ Join Date: 2009-02-16 Member: 66432Members
    I think I've seen a trend here. Errors will happen with syntax like this:


    S = {}
    S.Names= {}
    S.Names[0] = {}
    S.Names[0]['Name'] = 'Test' <----error line

    or similarly

    --MessageIndex and MessageIndex[6] are both tables defined in another file....


    MessageIndex[6]['energy'] = {Title = 'Energy', Text = 'Your current energy.' }

    Something with the way these tables are formed is causing it to come up as nil in your new build
    Off Topic Disagree Agree Awesome
  • Onos Ate MeOnos Ate Me Join Date: 2010-12-31 Member: 76072Members, NS2 Playtester, Squad Five Blue
    I fixed the assignment bug. NS2Docs will now document <i>S</i> and <i>MessageIndex</i> in the following code:
    <!--c1--><div class='codetop'>CODE</div><div class='codemain'><!--ec1-->S = {}
    S.Names= {}
    S.Names[0] = {}
    S.Names[0]['Name'] = 'Test'
    MessageIndex = {}
    MessageIndex[6]['energy'] = {Title = 'Energy', Text = 'Your current energy.' }<!--c2--></div><!--ec2-->

    <a href="http://damien.kodingen.com/ns2docs/ns2docs-4.zip" target="_blank">Download NS2Docs Build 4</a>
    Off Topic Disagree Agree Awesome
  • ☼Lap☼☼Lap☼ Join Date: 2009-02-16 Member: 66432Members
    That fixed everything. No problems anymore. Great program and your response time is amazing.
    Off Topic Disagree Agree Awesome
  • BJHBnade_spammerBJHBnade_spammer Join Date: 2005-02-25 Member: 42431Members
    edited August 2011
    if it works how i think it does this is definitely a nice thing that anyone that wants to make mods should use as correct me if im wrong as i understand it will tell where certain lua commands are defined initially so you can redefine or make sure you get stuff like order of operations as commands are concerned in order to interrupt where they are changed and in order to try and call them before other parts of the script do. so thanks very much Onos Ate Me as im sure this is an invaluable tool to those that dont want to take the time and look through all of the lua files
    Off Topic Disagree Agree Awesome
  • MurphyIdiotMurphyIdiot NS2 programmer Join Date: 2008-04-17 Member: 64095Members, Super Administrators, NS2 Developer, Subnautica Developer, Pistachionauts, Future Perfect Developer
    Very cool! I am going to be using this quite often I suspect :D
    Off Topic Disagree Agree Awesome
  • Racer1Racer1 Join Date: 2002-11-22 Member: 9615Members
    Would it possible to get this auto-generated for each build and placed on the NS2 website somewhere? - maybe the wiki or even a "Development" page all to itself.
    Off Topic Disagree Agree Awesome
  • MurphyIdiotMurphyIdiot NS2 programmer Join Date: 2008-04-17 Member: 64095Members, Super Administrators, NS2 Developer, Subnautica Developer, Pistachionauts, Future Perfect Developer
    <!--quoteo(post=1872555:date=Sep 1 2011, 09:53 AM:name=Racer1)--><div class='quotetop'>QUOTE (Racer1 @ Sep 1 2011, 09:53 AM) <a href="index.php?act=findpost&pid=1872555"><{POST_SNAPBACK}></a></div><div class='quotemain'><!--quotec-->Would it possible to get this auto-generated for each build and placed on the NS2 website somewhere? - maybe the wiki or even a "Development" page all to itself.<!--QuoteEnd--></div><!--QuoteEEnd-->

    Yes, we will try to work something out soon.
    Off Topic Disagree Agree Awesome
  • rgbDreamerrgbDreamer Join Date: 2011-10-02 Member: 125190Members
    Could an Admin sticky this? These are clutch to anyone modding NS2.
    Off Topic Disagree Agree Awesome
  • aeroripperaeroripper Join Date: 2005-02-25 Member: 42471NS1 Playtester, Forum Moderators, Constellation
    <!--quoteo--><div class='quotetop'>QUOTE </div><div class='quotemain'><!--quotec-->Could an Admin sticky this? These are clutch to anyone modding NS2.<!--QuoteEnd--></div><!--QuoteEEnd-->

    Done.
    Off Topic Disagree Agree Awesome
  • Onos Ate MeOnos Ate Me Join Date: 2010-12-31 Member: 76072Members, NS2 Playtester, Squad Five Blue
    <!--sizeo:4--><span style="font-size:14pt;line-height:100%"><!--/sizeo--><a href="http://damien.kodingen.com/187/tables/index.html" target="_blank">Ns2Docs Build 5 Preview</a><!--sizec--></span><!--/sizec-->
    I've update the docs with the preview of <a href="http://damien.kodingen.com/187/tables/index.html" target="_blank">Ns2Docs build 5</a>. There are lots of changes but the big ones are:
    <ul><li> complete interface overhaul to reduce redundancy</li><li> <a href="http://damien.kodingen.com/187/mixins/index.html" target="_blank">mixin support</a></li><li> bugs in displaying variables should be gone</li><li> globals are store in one file instead of across many to increase search-ability</li><li> tables have a bunch of ways to search their data</li></ul>

    Works with IE9, Chrome, Firefox, Safari. I haven't checked whether IE 7 or 8 render the pages properly.

    <a href="http://damien.kodingen.com/187/tables/Onos/index.html" target="_blank"><img src="http://img6.imageshack.us/img6/8047/nsdy.png" border="0" class="linked-image" /></a>
    Off Topic Disagree Agree Awesome
  • BJHBnade_spammerBJHBnade_spammer Join Date: 2005-02-25 Member: 42431Members
    i just noticed Onos has no children! lol

    and you sir are a coding ninja.

    can i have your babies.
    j/k

    but seriously what do you actually do for a living? make games? or make software?
    Off Topic Disagree Agree Awesome
  • Onos Ate MeOnos Ate Me Join Date: 2010-12-31 Member: 76072Members, NS2 Playtester, Squad Five Blue
    Updated the <a href="http://damien.kodingen.com/189/tables/" target="_blank">docs to build 189</a>.
    Off Topic Disagree Agree Awesome
  • aeroripperaeroripper Join Date: 2005-02-25 Member: 42471NS1 Playtester, Forum Moderators, Constellation
    Onos Ate Me you're a 1 man mod making army!
    Off Topic Disagree Agree Awesome
  • Onos Ate MeOnos Ate Me Join Date: 2010-12-31 Member: 76072Members, NS2 Playtester, Squad Five Blue
    Updated the <a href="http://dl.dropbox.com/u/53107776/ns2docs/190/tables/index.html" target="_blank">docs to build 190</a>
    Off Topic Disagree Agree Awesome
  • Soul_RiderSoul_Rider Mod Bean Join Date: 2004-06-19 Member: 29388Members, Constellation, Squad Five Blue
    <!--quoteo(post=1893775:date=Jan 12 2012, 08:17 AM:name=Onos Ate Me)--><div class='quotetop'>QUOTE (Onos Ate Me @ Jan 12 2012, 08:17 AM) <a href="index.php?act=findpost&pid=1893775"><{POST_SNAPBACK}></a></div><div class='quotemain'><!--quotec-->Updated the <a href="http://dl.dropbox.com/u/53107776/ns2docs/190/tables/index.html" target="_blank">docs to build 190</a><!--QuoteEnd--></div><!--QuoteEEnd-->

    Amazing, fantastic and thank you :)
    Off Topic Disagree Agree Awesome
  • Onos Ate MeOnos Ate Me Join Date: 2010-12-31 Member: 76072Members, NS2 Playtester, Squad Five Blue
    Updated to <a href="http://dl.dropbox.com/u/53107776/ns2docs/193/tables/index.html" target="_blank">build 193</a>
    Docs for <a href="http://dl.dropbox.com/u/53107776/ns2docs/electric/1/tables/index.html" target="_blank">Electric Build 1</a>
    Off Topic Disagree Agree Awesome
  • HarimauHarimau Join Date: 2007-12-24 Member: 63250Members
    Is there a search function for your live demo?
    Off Topic Disagree Agree Awesome
  • Onos Ate MeOnos Ate Me Join Date: 2010-12-31 Member: 76072Members, NS2 Playtester, Squad Five Blue
    <!--quoteo(post=1897392:date=Jan 25 2012, 06:32 PM:name=Harimau)--><div class='quotetop'>QUOTE (Harimau @ Jan 25 2012, 06:32 PM) <a href="index.php?act=findpost&pid=1897392"><{POST_SNAPBACK}></a></div><div class='quotemain'><!--quotec-->Is there a search function for your live demo?<!--QuoteEnd--></div><!--QuoteEEnd-->
    Tables have a basic search function when javascript is enabled. When I'm unsure where to find the data I'm looking for I'll either use the <i>Find in Files</i> search function in Notepad++ or use <a href="http://dl.dropbox.com/u/53107776/print.lua" target="_blank">this script</a> which will add <i>print</i> to the console commands in NS2. To use the command type <i>print TABLENAME</i> into the console (e.g. <i>print Player</i> to display all the fields for the Player class). Use <i>print TABLENAME FILTER</i> to restrict results (e.g. <i>print Player health</i> to display all fields inside Player with names containing <i>health</i>. <i>print _G</i> will display all the globals currently declared in NS2.
    Off Topic Disagree Agree Awesome
  • Soul_RiderSoul_Rider Mod Bean Join Date: 2004-06-19 Member: 29388Members, Constellation, Squad Five Blue
    Hi Onos,

    First off, this is really helpful to me, thanks for all your hardwork.

    Secondly, how difficult would it be for you to add the option to output a UML class chart?

    If it's a lot of hassle, don't worry, it's just an idea I had as I'm making my own class charts at the moment and it's taking me a while :)
    Off Topic Disagree Agree Awesome
  • Onos Ate MeOnos Ate Me Join Date: 2010-12-31 Member: 76072Members, NS2 Playtester, Squad Five Blue
    I've updated <a href="http://dl.dropbox.com/u/53107776/ns2docs/Ns2Docs%20Build%201.zip" target="_blank">NS2Docs</a> so that it can now output either Json or Html. Also, the source code to is now hosted on <a href="https://github.com/DamienHauta/Ns2Docs.git" target="_blank">GitHub</a>

    <a href="http://dl.dropbox.com/u/53107776/ns2docs/Ns2Docs%20Build%201.zip" target="_blank">Download Ns2Docs</a>
    Off Topic Disagree Agree Awesome
  • Onos Ate MeOnos Ate Me Join Date: 2010-12-31 Member: 76072Members, NS2 Playtester, Squad Five Blue
    <a href="http://dl.dropbox.com/u/53107776/ns2docs/210/tables/index.html" target="_blank">Updated to build 210</a>

    <a href="http://dl.dropbox.com/u/53107776/review/210/210vs209.html" target="_blank">Contextual diff with 209</a>
    <a href="http://dl.dropbox.com/u/53107776/review/210/210vs208.html" target="_blank">Contextual diff with 208</a>
    Off Topic Disagree Agree Awesome
Sign In or Register to comment.