https://github.com/tenable/nasldoc
A documentation generator for NASL.
https://github.com/tenable/nasldoc
Last synced: about 1 year ago
JSON representation
A documentation generator for NASL.
- Host: GitHub
- URL: https://github.com/tenable/nasldoc
- Owner: tenable
- License: bsd-3-clause
- Created: 2011-07-15T00:44:23.000Z (almost 15 years ago)
- Default Branch: master
- Last Pushed: 2022-05-31T16:38:12.000Z (about 4 years ago)
- Last Synced: 2024-10-20T06:20:24.114Z (over 1 year ago)
- Language: Ruby
- Homepage: http://www.tenable.com/products/nessus
- Size: 311 KB
- Stars: 17
- Watchers: 19
- Forks: 4
- Open Issues: 3
-
Metadata Files:
- Readme: README.markdown
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# 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 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:
nasldoc
- <%= File.basename(file) %>
<% @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(".", "_") %>
<% end %>