Commit 16703a57 authored by Alexis Brenon's avatar Alexis Brenon
Browse files

馃毀馃摑 Complete documentation

parent 2e938355
--- Foreign function interface management.
--
-- Handle unique declaration of C functions
-- @module utils.ffi_cdef
-- @author Alexis BRENON <brenon.alexis+arcades@gmail.com>
local ffi = require('ffi') -- Lua <-> C bindings
......@@ -39,13 +40,13 @@ local function load_lib(alt_names)
end
---Table of the `gobject` library's function
-- @table gobject
-- @tfield table gobject
---Table of the `cairo` library's function
-- @table cairo
-- @tfield table cairo
---Table of the `rsvg` library's function
-- @table rsvg
-- @tfield table rsvg
--- @export
return {
......
--- Package management.
--
-- Re-usable code to declare a package.
-- This package will automatically discover sub-packages and sub-modules
-- and export them on demand.
--
-- Each package contains a `load_all()` function which recurcivelly loads
-- all sub-packages and modules.
-- @usage
-- -- mypackage.lua
-- return require('arcades.utils.package_loader')(...)
--
-- @usage
-- -- myscript.lua
-- mypackage = import('mypackage').load_all()
-- @module utils.package_loader
-- @author Alexis BRENON <brenon.alexis+arcades@gmail.com>
local paths = require('paths')
--- Build a filter function to find sub-modules.
-- @tparam string basepath Path of the current package
-- @treturn function A function which filter filenames below `basepath` to find sub-modules
local function filter_modules(basepath)
return function(filename)
return (
......@@ -10,6 +31,9 @@ local function filter_modules(basepath)
end
end
--- Build a filter function to find sub-packages.
-- @tparam string basepath Path of the current package
-- @treturn function A function which filter filenames below `basepath` to find sub-packages
local function filter_packages(basepath)
return function(filename)
return (
......@@ -20,6 +44,15 @@ local function filter_packages(basepath)
end
end
--- Public Methods
-- @section public-methods
--- Declare a package.
--
-- Declare a package named `package_name` and discover its sub-packages and modules.
-- @tparam string package_name Name of the package as used to `import` it
-- @treturn table The package
-- @function loader
local function loader(package_name)
local package = {} -- Returned package
local entities = {} -- Available modules and sub-packages (loaded on demand)
......@@ -39,7 +72,9 @@ local function loader(package_name)
entities[entity] = "package"
end
--- Allow user to load all discovered modules and sub-packages
--- Load all sub-packages and modules.
--
-- Allow user to load all discovered modules and sub-packages.
-- Useful for auto-completion in Torch
function package.load_all()
for name, type in pairs(entities) do
......
--- Module to setup some general configuration.
--- General configuration setup
-- @module utils.setup
-- @author Alexis BRENON <alexis.brenon@imag.fr>
local ffi = require('ffi')
......@@ -11,9 +12,15 @@ local arcades = require('arcades')
local Logger = require('arcades.utils.Logger')
local utils = require('arcades.utils.utils')
--- Private methods
-- @section public-methods
--- Private Methods
-- @section private-methods
--- Find a class in a given hierarchy.
-- @tparam string class_path A fully qualified class name
-- @tparam table base Hierarchy to search through
-- @treturn function Class constructor
-- @error nil The error message
-- @function _get_class
local function _get_class(class_path, base)
base = base or _G
local class = base
......@@ -37,9 +44,9 @@ local function _get_class(class_path, base)
return class, err
end
--- Initialize some torch dependant configuration.
--- Initialize Torch dependant configuration.
--
-- The passed parameter <code>opt</code> is updated to reflect the actual values
-- The passed parameter `opt` is updated to reflect the actual values
-- that Torch returned after trying to configure it.
-- @tparam[opt={}] table opt
-- @tparam string opt.tensor_type Torch default tensor type
......@@ -98,6 +105,10 @@ local function _torchSetup(opt)
end
end
--- Setup training and testing @{environment.BaseEnvironment|environments}.
-- @tparams table args Environments arguments
-- @treturn table `test` and `train` environments
-- @function _environment_setup
local function _environment_setup(args)
local envs = {}
local environment = require('arcades.environment')
......@@ -147,7 +158,11 @@ local function _environment_setup(args)
return envs
end
--- Setup an @{agent.BaseAgent|agent}.
-- @tparams table args Agent arguments
-- @tparams table environments Environments in which agent will act
-- @treturn agent.BaseAgent Instanciated agent
-- @function _agent_setup
local function _agent_setup(args, environments)
local agent
......@@ -181,6 +196,12 @@ local function _agent_setup(args, environments)
return agent
end
--- Setup an @{experiment.BaseExperiment|experiment}.
-- @tparam table args Experiment arguments
-- @tparam agent.BaseAgent agent Agent used for experiment
-- @tparam table environments Environments used for experiment
-- @treturn experiment.BaseExperiment Instanciated experiment
-- @function _experiment_setup
local function _experiment_setup(args, agent, environments)
local experiment
......@@ -211,13 +232,13 @@ local function _experiment_setup(args, agent, environments)
return experiment
end
--- Public methods
--- Public Methods
-- @section public-methods
--- Initialize configuration.
-- @tparam table opt Parsed command line arguments
-- @treturn experiment.BaseExperiment The loaded experiment, ready to run
-- @treturn table The updated <code>opt</code> table
-- @treturn table The updated `opt` table
-- @function setup
local function setup(opt)
assert(opt)
......@@ -234,6 +255,7 @@ local function setup(opt)
return experiment
end
--- @export
return {
setup = setup
}
--- SVG rendering logic.
--
-- Parse and build a @{utils.placeholder|manipulable} SVG object.
-- Then allow to render them to rasterized image.
-- This rely on different C library and thus on the
-- `ffi_cdef` module.
-- @warn A reimplementation based on class could be great.
-- @module utils.svg_renderer
-- @alias M
-- @author Alexis BRENON <alexis.brenon@imag.fr>
local ffi = require('ffi') -- Lua <-> C bindings
local clibs = require('arcades.utils.ffi_cdef') -- Assert FFI definitions have been done
-- Load required C libraries
......@@ -13,6 +24,26 @@ local placeholder = require('arcades.utils.placeholder')
local M = {}
--- Data Types
-- @section data-types
--- A manipulable SVG object.
-- @tfield string base_document Path to the SVG source file
-- @tfield integer width Dimen of the SVG file
-- @tfield integer height Dimen of the SVG file
-- @tfield table components List of SVG components (`string` or `placeholder`)
-- @tfield table placeholders @{utils.placeholder|Placeholders} indexed by their sensor ID
-- @table svg_object
-- @see utils.placeholder
--- Public Methods
-- @section public-methods
--- Instanciate an SVG object.
--
-- Build an SVG object from an SVG file.
-- @tparam string svg_path Path the SVG file to parse
-- @treturn svg_object The resulting `svg_object`
function M.prepare_svg_data(svg_path)
assert(svg_path, "No path to the SVG given!")
local document = xml.parse(svg_path, true) -- XML object of the SVG image
......@@ -36,10 +67,13 @@ function M.prepare_svg_data(svg_path)
return result
end
--- Recurcive funtion to parse SVG document, replacing variable components
-- with placeholders.
-- @tparam component string Current static component
--- Recurcive component creator.
--
-- Parse SVG document replacing variable components with placeholders or
-- concatenating constant components as single string.
-- @tparam string component Current constant component
-- @param element XML element to parse
-- @treturn string Current constant component
local function component_creator(component, element)
if type(element) == 'string' then
component = component .. element
......@@ -58,7 +92,7 @@ function M.prepare_svg_data(svg_path)
end
-- Close the current component after all its children
component = component .. "</" .. element.tag .. ">"
else
else -- A placeholder has been instanciated
-- Save the static component if any
if component ~= "" then
table.insert(svg.components, component)
......@@ -78,6 +112,9 @@ function M.prepare_svg_data(svg_path)
return svg
end
--- Convert an @{svg_object|SVG object} to a @{torch.Tensor/tensor.md/|Torch tensor}.
-- @tparam svg_object svg The `svg_object` to convert
-- @treturn torch.FloatTensor A @{torch.FloatTensor/tensor.md/} of size `depth x width x height`
function M.convert_SVG2Tensor(svg)
-- Generate the full SVG data with right values
local svg_data = {}
......
--- Utilities functions.
--
-- A set of functions that are not tidly linked to the
-- arcades logic and that can be freely used.
-- @module utils.utils
-- @alias module
-- @author Alexis BRENON <brenon.alexis+arcades@gmail.com>
local module = {}
--- Return a value sampled in a table
-- @tparam table t
--- Public Methods
-- @section public-methods
--- Randomly sample a value in a table.
-- @tparam table t List to sample from.
-- @return An element of the table
-- @treturn number The index of the returned element
function module.sample_in(t)
......@@ -10,6 +20,11 @@ function module.sample_in(t)
return t[idx], idx
end
--- Load a string representation of a table.
-- @param t Object to load
-- @treturn[1] table A table from the given string
-- @treturn[2] table `t` if it is a table
-- @treturn[3] nil
function module.load_table(t)
if type(t) == "string" then
local status, result = pcall(
......@@ -30,7 +45,7 @@ function module.load_table(t)
end
end
--- Try to cast a value.
--- Cast a value (if possible).
--
-- If this value is a string it will try to cast it to a number, a boolean, or
-- a table (casting its own values).
......@@ -59,6 +74,8 @@ function module.cast(v)
return v, type(v)
end
--- Load all arcades packages and modules.
-- @note Is it equivalent to `require('arcades').load_all()`?
function module.load_all()
require('arcades.agent').load_all()
require('arcades.environment').load_all()
......@@ -70,6 +87,9 @@ end
-- Copy of the new_print Torch function but return a string
-- Special case, don't print big Tensors (more than 25 elements), just their size
local ndepth = 6
--- Build a prettyfied representation of anything
-- @param ... Whatever you want
-- @treturn string A pretty string
function module.pretty_repr(...)
local result = {}
local function rawprint(o)
......@@ -113,7 +133,6 @@ function module.pretty_repr(...)
line('{}')
end
end
--require('mobdebug').start()
for i = 1,select('#',...) do
local obj = select(i,...)
if type(obj) ~= 'table' then
......
......@@ -18,6 +18,9 @@
.module-name {
word-break: break-all;
}
.module-summary {
font-size: 125%;
}
ul.parameters, ul.returns {
margin-bottom: 0.75em;
......
......@@ -23,6 +23,7 @@
# local project_kinds = {"Scripts", "Packages", "Modules", "Classes", "Examples"}
# local project_hierarchy = {}
# local project_hierarchy_current_root = nil
# for _, kind_name in ldoc.ipairs(project_kinds) do
# local hierarchy = {}
# local level_index = {}
......@@ -42,6 +43,9 @@
# end
# if i == #(k.names_hierarchy) then
# current_hierarchy[level_index[i]].self = k
# if k.name == (module and module.name) then
# project_hierarchy_current_root = current_hierarchy[level_index[i]]
# end
# end
# current_hierarchy = current_hierarchy[level_index[i]].subs
# end
......@@ -49,7 +53,13 @@
# end
# project_hierarchy[kind_name] = hierarchy
# end
# local module_kinds = {"Fields", "Metamethods", "Public Methods", "Private Methods", "Static Fields", "Static Functions"}
# local this_mod = project_hierarchy_current_root and project_hierarchy_current_root.self or {}
# ldoc.log("##", this_mod.kind, this_mod.name, "##")
# local module_kinds = {"Data Types", "Fields", "Metamethods", "Public Methods", "Private Methods", "Static Fields", "Static Functions"}
# local module_kinds_set = {}
# for i, kind in ldoc.ipairs(module_kinds) do module_kinds_set[kind] = i end
# local build_dropdown
# build_dropdown = function(m, _nav_ID, classes)
......@@ -120,9 +130,6 @@
<!-- **************************************************************** -->
# -------- contents of project ----------
# local this_mod = module and module.name
# ldoc.log("##", module and module.kind, this_mod, module and module.file, "##")
# -- ldoc.inspect(module or "nil")
<!-- Project navbar -->
<nav class="navbar navbar-expand-lg navbar-full navbar-dark bg-primary flex-column mb-2"
id="project-nav-accordion">
......@@ -247,6 +254,11 @@
</a>
# end
# else
# for kind_name, _ in module.kinds() do
# if not (module_kinds_set[kind_name] or module_kinds_set[kind_name:sub(1,-2)]) then
# ldoc.log("## WARN ## " .. kind_name .. " section will not be displayed...")
# end
# end
# for _, kind in ldoc.ipairs(module_kinds) do
# local items = module.kinds[kind] or module.kinds[kind .. " "]
# if items then
......@@ -271,13 +283,13 @@
</a>
# for item in items() do
</span>
<a class="list-group-item"
href="#$(escape(item.name))">
$(display_name(item))
</a>
# end
</div> <!-- Kinds sub-list -->
# end -- if kinds[kind]
# end -- for kinds in module
......@@ -356,7 +368,7 @@
<!-- -->
<!-- ***************************************************************** -->
<main class="col-xs-12 col-md-9">
<main class="col-12 col-md-9">
# if ldoc.body then -- verbatim HTML as contents; 'non-code' entries
......@@ -368,7 +380,7 @@
<header class="row module-header mb-3">
<!-- Module name and summary -->
<div class="col-xs-12">
<div class="col-12">
<h2>
$(ldoc.module_typename(module))
<code class="module-name">$(module.mod_name)</code>
......@@ -384,7 +396,7 @@
# local one_column_nav_display = ldoc.one and "" or "hidden-md-up"
<!-- Info and references -->
<div class="col-xs-12 d-lg-none card bg-info module-info">
<div class="col-12 d-lg-none card bg-info module-info">
<div class="row">
# local sub_col_width = 12 / (
......@@ -395,7 +407,7 @@
# sub_col_width = sub_col_width == 12 and "12" or sub_col_width == 6 and "6" or "4"
# if module.info then
<div class="col-xs-12 col-md-$(escape(sub_col_width))">
<div class="col-12 col-md-$(escape(sub_col_width))">
<strong class="card-title">Info:</strong>
<ul class="card-text list-unstyled">
......@@ -417,7 +429,7 @@
# end -- if module.info
# if module.tags.include then
<div class="col-xs-12 col-md-$(escape(sub_col_width))">
<div class="col-12 col-md-$(escape(sub_col_width))">
<strong class="card-title">References:</strong>
<p class="card-text">
$(M(ldoc.include_file(module.tags.include)))
......@@ -426,7 +438,7 @@
# end
# if module.see then
<div class="col-xs-12 col-md-$(escape(sub_col_width))">
<div class="col-12 col-md-$(escape(sub_col_width))">
<strong class="card-title">See also:</strong>
<ul class="card-text list-unstyled">
# for see in iter(module.see) do
......@@ -443,7 +455,7 @@
# if module.usage then
<!-- Module usage-->
<div class="col-xs-12 module-usage">
<div class="col-12 module-usage">
<strong>Usage:</strong>
<ul class="list-unstyled">
# for usage in iter(module.usage) do
......@@ -514,7 +526,7 @@
<h4>$(display_name(item))</h4>
# if ldoc.prettify_files and ldoc.is_file_prettified[item.module.file.filename] then
<a class="float-xs-right" href="$(escape(ldoc.source_ref(item)))">
<a class="float-right" href="$(escape(ldoc.source_ref(item)))">
<code>line $(escape(item.lineno))</code>
</a>
# end
......
......@@ -43,7 +43,7 @@ local torchUrls = {
Torch = "https://github.com/torch/torch7/blob/master/doc/%s",
nn = "https://github.com/torch/nn/blob/master/doc/%s",
}
custom_see_handler('^(torch%..*)/.*/$', function(name, file)
custom_see_handler('^(torch%..*)/(.*)/$', function(name, file)
local url = torchUrls.Torch:format(file)
return name, url
end)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment