Stingray plugin documentation generation with adoc.

Author: Jarrod Smith

README.md

@@ -91,6 +91,7 @@ See [the wiki](https://github.com/AutodeskGames/stingray-plugin/wiki/How-to-crea
 -   `stingray_sdk`: Autodesk Interactive editor and engine C/C++ header based plugin SDK downloaded by `spm`.
 -   `tools`: Various build tools downloaded by `spm`.
 -   `make.rb`: Build interface script. Execute `make.rb --help` to see all the options.
+-	`docs`:	Ruby script and template to automatically generate documentation for your plugin using Adoc.
 
 Once you've successfully built the Autodesk Interactive plugin, you can zip the `plugin` folder and **distribute** your plugin. For help getting started with with the Autodesk Interactive SDK, see the tutorial videos and topics in the [main Autodesk Interactive SDK Help](http://help.autodesk.com/view/Stingray/ENU/?guid=__sdk_help_introduction_html).
 
@@ -99,6 +100,19 @@ Once you've successfully built the Autodesk Interactive plugin, you can zip the
 -   `stingray-example.plugin`: Initial plugin descriptor. It is strongly recommended to rename the file name of this file.
 -   `sample_project/`: Example project that demonstrate how your plugin works.
 
+## Documentation
+
+*Note: This currently requires Stingray source access due to the dependency on [Adoc](https://git.autodesk.com/gameware/stingray/tree/develop/docs/build/tools/adoc).*
+
+In the [`./docs`](./docs) directory there's a ruby script that will generate documentation for your plugin using Adoc. Refer to the comments in the script and the other documentation example files in the `./docs` dir, as well as the [Stingray repository /docs readme](https://git.autodesk.com/gameware/stingray/tree/develop/docs) to learn how to annotate your code comments for Adoc parsing.
+
+You do not need to install the `ixg-doc-tools` to generate your plugin docs. Just define the `%SR_SOURCE_DIR%` environment variable (e.g. `c:\dev\stingray`) or modify the line in [`make_plugin_docs.rb`](./docs/make_plugin_docs.rb). Then run the script and refer to the output directory in the console to view the generated documentation.
+
+Usage:
+```
+ruby docs/make_plugin_docs.rb
+```
+
 ## More help
 
 Please see the [Autodesk Interactive SDK Help](http://help-staging.autodesk.com/view/Stingray/ENU/?contextId=SDK_HOME) for more details on working with plug-ins, API reference documentation, and more.

docs/config_adoc_lua_reference.json

@@ -0,0 +1,10 @@
+
+	{
+		"output_path":		"$(SR_DOC_OUTPUT_DIR)/lua_HTML",
+		"index_title":		"My Plugin Documentation",
+		"index_file":		"./source/lua_reference/index.txt",
+		"images_path":		"./source/lua_reference/images",
+		"version_history":	"./source/lua_reference/versions",
+		"save_version_as":	"",
+		"ref_id":			"lua_ref"
+	}

docs/make_plugin_docs.rb

@@ -0,0 +1,63 @@
+#******************************************************************************
+#
+# make_plugin_docs.rb - Builds Adoc documentation for your plugin project.
+#
+# Details of marking up your source for Adoc processing can be found here:
+# https://git.autodesk.com/gameware/stingray/tree/develop/docs
+#
+# Usage:
+#   1) Modify the configuration variables below if needed.
+#   2) ruby make_plugin_docs.rb
+#******************************************************************************
+
+require 'optparse'
+require 'fileutils'
+
+# Utility functions
+class String
+	def colorize(color_code); $stdout.isatty() ? "\e[#{color_code}m#{self}\e[0m" : self; end
+	def black; colorize(30) end
+	def red; colorize(31) end
+	def green; colorize(32) end
+	def yellow; colorize(33) end
+	def blue; colorize(34) end
+	def magenta; colorize(35) end
+	def cyan; colorize(36) end
+	def gray; colorize(37) end
+	def default; colorize(39) end
+	def bold; $stdout.isatty() ? "\e[1m#{self}\e[22m" : self; end
+end
+
+$script_dir = File.expand_path(File.dirname(__FILE__))
+$docs_dir = $script_dir
+$plugin_dir = "#{$script_dir}/.."
+
+#**************************************************************************
+# Change these depending upon your plugin's needs.
+$explicit_engine_dir = nil					# Path to Stingray source directory e.g. "c:\dev\stingray", alternatively set the %SR_SOURCE_DIR% environment variable.
+$input_dirs = [
+    "#{$plugin_dir}/engine",				# For Lua API documentation.
+    "#{$docs_dir}/source/samples",
+    "#{$docs_dir}/source/lua_reference",
+	"#{$plugin_dir}/plugin/sample_project"
+	# Add any additional paths for adoc to process as needed.
+]
+$output_dir = "#{$docs_dir}/output"
+$config_path = "#{$docs_dir}/config_adoc_lua_reference.json"
+#**************************************************************************
+
+$engine_dir = $explicit_engine_dir || ENV["SR_SOURCE_DIR"]
+if $engine_dir == nil or $engine_dir.empty?
+    STDERR.puts "\nPlease define the %SR_SOURCE_DIR% environment variable or modify this script's $explicit_engine_dir to point to your Stingray source directory.".bold.red
+    exit 1
+end
+
+$make_docs = "#{$engine_dir}/docs/build/make_docs.rb"
+puts "Calling #{$make_docs}..."
+STDOUT.flush
+# This only builds the Lua API documentation. You can modify this to build other documentation types as needed.
+$command = ["ruby #{$make_docs} --lua-ref", "--input",  "\"#{$input_dirs.join("\",\"")}\"",
+																	 "--output", "\"#{$output_dir}\"",
+																	 "--config", "\"#{$config_path}\"",
+																	 *ARGV].join(" ")	# Pass any command line args through.
+system($command)

docs/source/lua_reference/categories.txt

@@ -0,0 +1,11 @@
+@adoc lua
+
+@ns stingray : nil
+@des The main namespace for the Lua API elements provided by the Stingray3D engine.
+
+@cat my_category My Category
+@des A collection of related documentation items.
+
+@obj MyObject : lightuserdata
+@des My test object.
+@grp my_category

docs/source/lua_reference/images/add_plugin.png

@@ -0,0 +1,12 @@
+Welcome to My Plugin!
+
+More details can be found here:
+
+    *   [A PDF](../relative/path/to/some.pdf)
+    *   [An external link](https://www.autodesk.com/products/stingray)
+
+The best place to begin is by going through the [categories](categories.html), which cover the entire API grouped by topic. The category descriptions provide an overview. Alternatively, you can take a look at the [list of all objects](objects.html), or start exploring the elements exposed in the main [`stingray` namespace](ns_stingray.html).
+
+Be sure to enable the plugin in the Stingray Editor:
+
+![Example of including an image](add_plugin.png)

docs/source/lua_reference/index.txt

@@ -0,0 +1,42 @@
+-- @adoc lua
+-- @exa my_sample Sample Title
+-- @des My sample description.
+
+function pick_unit(world, camera)
+    if SimpleProject then
+        world = world or SimpleProject.world
+        camera = camera or stingray.Unit.camera(SimpleProject.camera_unit, 1)
+    end
+    -- get the X and Y screen coordinates to pick from.
+    local width, height = stingray.Application.back_buffer_size()
+    local pick_x_pos = math.floor(width / 2)
+    local pick_y_pos = math.floor(height / 2)
+    if stingray.Window and stingray.Window.show_cursor() then
+        pick_x_pos = stingray.Mouse.axis(stingray.Mouse.axis_id("cursor"), stingray.Mouse.RAW, 3).x
+        pick_y_pos = stingray.Mouse.axis(stingray.Mouse.axis_id("cursor"), stingray.Mouse.RAW, 3).y
+    end
+    local depth = 0.5
+
+    -- translate the screen coordinates to a position in 3D world space.
+    local screen_pos_in_scene = stingray.Camera.screen_to_world(camera, stingray.Vector3(pick_x_pos, pick_y_pos, 0), depth)
+    local camera_position = stingray.Camera.world_position(camera)
+
+    -- get the direction from the camera position to the 3D starting coordinates.
+    local camera_to_mouse_direction = stingray.Vector3.normalize(screen_pos_in_scene  - camera_position);
+
+    -- cast a physics ray into the scene, starting from the camera position, in the
+    -- direction toward the picked screen position.
+    local physics_world = stingray.World.physics_world(world)
+    local foundCollision, collisionPos, distance, normal, actor =
+            stingray.PhysicsWorld.raycast(
+                physics_world, camera_position, camera_to_mouse_direction, "closest"
+                )
+
+    local actor_obj = nil
+    if (foundCollision) then -- we have hit a unit.
+        actor_obj = stingray.Actor.unit(actor)
+    end
+    return actor_obj, collisionPos, distance, normal, actor
+end
+-- @adoc lua
+-- @exa my_sample Sample Title