nasldoc¶ ↑
Installation¶ ↑
Installation is really easy, all you need to do is gem install!
% gem install nasldoc
Usage¶ ↑
Using nasldoc
is fairly simple; just pass it a directory or a single file that you want to generate the documentation for. nasldoc
is designed to only parse .inc files which special comment markup.
% nasldoc /opt/nessus/lib/nessus/plugins/
This will cause a directory called nasldoc/
to be created in your current directory. This directory will contain all of the generated HTML documents. After running nasldoc
, open index.html
inside of nasldoc/
and view the documentation.
Comment Markup¶ ↑
nasldoc
comments are inclosed in ## blocks and use special tags to mark items. Currently, there are only 3 tags. Tags can be added in a matter of minutes to the parser.
nasldoc supports several markup tags:
-
@param - used to label named arguments to a function
-
@anonparam - used to label anonymous arguments to a function
-
@return - what the function returns
-
@deprecated - notation for functions that shouldn't be used
-
@nessus - minimum Nessus version supported
-
@category - type of category for the function
-
@remark - special notes or remarks
Function Description Block¶ ↑
The function description block is free form text from the first ## block to the first @tag in the nasldoc
body. The lines are split on the # and rejoined with spaces.
Example:
## # An example addition function in NASL # # @param arg1 first number to add # @param arg2 second number to add # # @return the sum of arg1 and arg2 ## function add(arg1, arg2) { return (arg1 + arg2); }
Variable types¶ ↑
If you'd like, you can provide variable type descriptions. The syntax is as follows:
## # An example addition function in NASL # # @param <arg1:int> first number to add # @param [arg2:int] second number to add # # @return the sum of arg1 and arg2 ## function add(arg1, arg2) { return (arg1 + arg2); }
You can wrap the name:type tuple using either '[]' or '<>'.
Templates¶ ↑
nasldoc
uses the ERB templating engine to make generating the output HTML trivial. Attached is an example of the sidebar; ruby code can be injected to help generate the layout.
Example:
<html> <head> <title>nasldoc</title> <link rel = 'stylesheet' type= 'text/css' href='stylesheet.css'> </head> <body> <img src='nessus.jpg' /> <br><br><br> <ul> <% @file_list.each_with_index do |file, i| %> <% row_class = i % 2 == 0 ? "even" : "odd" %> <% output_file = file.gsub(".", "_") %> <% output_file = File.basename(file).gsub(".", "_") %> <li class="<%= row_class %>"><a href='<%= output_file %>.html' target='content'><%= File.basename(file) %></a></li> <% end %> </ul> <br><br><br> <ul><a href='overview.html' target='content'>Home</a></ul> </body> </html>