diff --git a/README.md b/README.md index 77431d7..504ec9b 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ You'll find a sample plug-in that is already set up with some basic content, and - `spm.rb` fetches and installs build packages and external libraries. It's called internally by `make.rb`, but you can also use it on its own as well if your plug-in has other dependencies that you want to download automatically. - `cmake` generates and compiles Visual Studio solutions for the native plug-in extensions. -For more information about plug-ins, how they work, and what you can do with them, see the [Autodesk Interactive SDK Help](http://help-staging.autodesk.com/view/Stingray/ENU/?contextId=SDK_HOME). +For more information about plug-ins, how they work, and what you can do with them, see the [Autodesk Interactive SDK Help](http://help.autodesk.com/view/Stingray/ENU/?contextId=SDK_HOME). ## Step 1. Install prerequisites @@ -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,9 +100,22 @@ 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.* + +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 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. +Please see the [Autodesk Interactive SDK Help](http://help.autodesk.com/view/Stingray/ENU/?contextId=SDK_HOME) for more details on working with plug-ins, API reference documentation, and more. ## Stay in touch! diff --git a/docs/config_adoc_lua_reference.json b/docs/config_adoc_lua_reference.json new file mode 100644 index 0000000..cfdbb16 --- /dev/null +++ b/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" + } diff --git a/docs/make_plugin_docs.rb b/docs/make_plugin_docs.rb new file mode 100644 index 0000000..f130d3c --- /dev/null +++ b/docs/make_plugin_docs.rb @@ -0,0 +1,68 @@ +#****************************************************************************** +# +# make_plugin_docs.rb - Builds Adoc documentation for your plugin project. +# +# Note: This script requires Stingray source access to run, due to the +# dependency on Adoc. +# +# Refer to the comments in this script to configure for documentation generation. +# See also the other documentation example files in the `./docs` dir, as well as +# the Stingray repository docs readme to learn how to annotate your code comments +# for Adoc parsing. +# +# 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) \ No newline at end of file diff --git a/docs/source/lua_reference/categories.txt b/docs/source/lua_reference/categories.txt new file mode 100644 index 0000000..79be616 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/source/lua_reference/images/add_plugin.png b/docs/source/lua_reference/images/add_plugin.png new file mode 100644 index 0000000..089940f Binary files /dev/null and b/docs/source/lua_reference/images/add_plugin.png differ diff --git a/docs/source/lua_reference/index.txt b/docs/source/lua_reference/index.txt new file mode 100644 index 0000000..e454442 --- /dev/null +++ b/docs/source/lua_reference/index.txt @@ -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) diff --git a/docs/source/samples/my_sample.lua b/docs/source/samples/my_sample.lua new file mode 100644 index 0000000..d61bb8e --- /dev/null +++ b/docs/source/samples/my_sample.lua @@ -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 diff --git a/plugin/example.stingray_plugin b/plugin/example.stingray_plugin index fffb2af..88eb800 100644 --- a/plugin/example.stingray_plugin +++ b/plugin/example.stingray_plugin @@ -13,7 +13,7 @@ author = { name = "Jonathan Schmidt" email = "jonathan.schmidt@autodesk.com" company = "Autodesk Inc." - url = "https://git.autodesk.com/gameware/stingray-plugin" + url = "https://github.com/AutodeskGames/stingray-plugin" } keywords = ["autodesk", "interactive", "stingray", "plugin", "example"]