diff --git a/CMakeLists.txt b/CMakeLists.txt index 789ff98ce..4ca397d47 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -286,13 +286,13 @@ if(GENERATE_DOC) # Copy the aliases to the build directory file(COPY ${SOURCE_DIR}/docs/aliases DESTINATION ${BUILD_DIR}/docs) - file(COPY ${SOURCE_DIR}/docs/ldoc.css DESTINATION ${BUILD_DIR}/docs) + + # Copy ldoc files. + configure_file(${SOURCE_DIR}/docs/ldoc.css ${BUILD_DIR}/docs COPYONLY) + configure_file(${SOURCE_DIR}/docs/ldoc.ltp ${BUILD_DIR}/docs COPYONLY) add_custom_target(ldoc ALL - DEPENDS - ${BUILD_DIR}/doc/index.html - ${BUILD_DIR}/docs/ldoc.css - generate_awesomerc + DEPENDS ${BUILD_DIR}/doc/index.html ) if (STRICT_TESTS) @@ -305,7 +305,15 @@ if(GENERATE_DOC) OUTPUT ${BUILD_DIR}/doc/index.html COMMAND ${LDOC_EXECUTABLE} ${ldoc_args} WORKING_DIRECTORY ${AWE_DOC_DIR} - DEPENDS ${AWE_SRCS} ${AWE_LUA_FILES} ${AWE_MD_FILES} ${BUILD_DIR}/docs/config.ld generate-examples ${BUILD_DIR}/docs/ldoc.css + DEPENDS + ${AWE_SRCS} + ${AWE_LUA_FILES} + ${AWE_MD_FILES} + ${BUILD_DIR}/docs/config.ld + ${BUILD_DIR}/docs/ldoc.css + ${BUILD_DIR}/docs/ldoc.ltp + generate_awesomerc + generate-examples COMMENT "Generating API documentation${ldoc_desc_suffix}") endif() # }}} diff --git a/docs/config.ld b/docs/config.ld index 0d783ace1..7e9164c39 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -11,6 +11,7 @@ dir='../doc' -- Make the docs prettier pretty='lua' style=true +template=true backtick_references=true merge=true use_markdown_titles=true diff --git a/docs/ldoc.ltp b/docs/ldoc.ltp new file mode 100644 index 000000000..f7a7501ea --- /dev/null +++ b/docs/ldoc.ltp @@ -0,0 +1,314 @@ + +# local title = module and ldoc.module_typename(module).." "..module.name.." - "..ldoc.title or ldoc.title + + + + $(title) + +# if ldoc.custom_css then -- add custom CSS file if configured. + +# end + + + +
+ +
+ +
+
+
+ + +
+ +# local no_spaces = ldoc.no_spaces +# local use_li = ldoc.use_li +# local display_name = ldoc.display_name +# local iter = ldoc.modules.iter +# local function M(txt,item) return ldoc.markup(txt,item,ldoc.plain) end +# local nowrap = ldoc.wrap and '' or 'nowrap' + + + + + +
+ +# if ldoc.body then -- verbatim HTML as contents; 'non-code' entries + $(ldoc.body) +# elseif module then -- module documentation +

$(ldoc.module_typename(module)) $(module.name)

+

$(M(module.summary,module))

+

$(M(module.description,module))

+# if module.tags.include then + $(M(ldoc.include_file(module.tags.include))) +# end +# if module.see then +# local li,il = use_li(module.see) +

See also:

+
    +# for see in iter(module.see) do + $(li)$(see.label)$(il) +# end -- for +
+# end -- if see +# if module.usage then +# local li,il = use_li(module.usage) +

Usage:

+
    +# for usage in iter(module.usage) do + $(li)
    $(ldoc.escape(usage))
    $(il) +# end -- for +
+# end -- if usage +# if module.info then +

Info:

+
    +# for tag, value in module.info:iter() do +
  • $(tag): $(M(value,module))
    • +# end +
+# end -- if module.info + + +# if not ldoc.no_summary then +# -- bang out the tables of item types for this module (e.g Functions, Tables, etc) +# for kind,items in module.kinds() do +

$(kind)

+ +# for item in items() do + + + + +# end -- for items +
$(display_name(item))$(M(item.summary,item))
+#end -- for kinds + +
+
+ +#end -- if not no_summary + +# --- currently works for both Functions and Tables. The params field either contains +# --- function parameters or table fields. +# local show_return = not ldoc.no_return_or_parms +# local show_parms = show_return +# for kind, items in module.kinds() do +# local kitem = module.kinds:get_item(kind) +# local has_description = kitem and ldoc.descript(kitem) ~= "" +

$(kind)

+ $(M(module.kinds:get_section_description(kind),nil)) +# if kitem then +# if has_description then +
+ $(M(ldoc.descript(kitem),kitem)) +
+# end +# if kitem.usage then +

Usage:

+ 
$(ldoc.prettify(kitem.usage[1]))
+# end +# end +
+# for item in items() do +
+ + $(display_name(item)) +# if ldoc.prettify_files and ldoc.is_file_prettified[item.module.file.filename] then + line $(item.lineno) +# end +
+
+ $(M(ldoc.descript(item),item)) + +# if ldoc.custom_tags then +# for custom in iter(ldoc.custom_tags) do +# local tag = item.tags[custom[1]] +# if tag and not custom.hidden then +# local li,il = use_li(tag) +

$(custom.title or custom[1]):

+
    +# for value in iter(tag) do + $(li)$(custom.format and custom.format(value) or M(value))$(il) +# end -- for +# end -- if tag +
+# end -- iter tags +# end + +# if show_parms and item.params and #item.params > 0 then +# local subnames = module.kinds:type_of(item).subnames +# if subnames then +

$(subnames):

+# end +
    +# for parm in iter(item.params) do +# local param,sublist = item:subparam(parm) +# if sublist then +
  • $(sublist)$(M(item.params.map[sublist],item)) +
      +# end +# for p in iter(param) do +# local name,tp,def = item:display_name_of(p), ldoc.typename(item:type_of_param(p)), item:default_of_param(p) +
    • $(name) +# if tp ~= '' then + $(tp) +# end + $(M(item.params.map[p],item)) +# if def == true then + (optional) +# elseif def then + (default $(def)) +# end +# if item:readonly(p) then + readonly +# end +
      • +# end +# if sublist then +
    +# end +# end -- for +
+# end -- if params + +# if show_return and item.retgroups then local groups = item.retgroups +

Returns:

+# for i,group in ldoc.ipairs(groups) do local li,il = use_li(group) +
    +# for r in group:iter() do local type, ctypes = item:return_type(r); local rt = ldoc.typename(type) + $(li) +# if rt ~= '' then + $(rt) +# end + $(M(r.text,item))$(il) +# if ctypes then +
      +# for c in ctypes:iter() do +
    • $(c.name) + $(ldoc.typename(c.type)) + $(M(c.comment,item))
      • +# end +
    +# end -- if ctypes +# end -- for r +
+# if i < #groups then +

Or

+# end +# end -- for group +# end -- if returns + +# if show_return and item.raise then +

Raises:

+ $(M(item.raise,item)) +# end + +# if item.see then +# local li,il = use_li(item.see) +

See also:

+
    +# for see in iter(item.see) do + $(li)$(see.label)$(il) +# end -- for +
+# end -- if see + +# if item.usage then +# local li,il = use_li(item.usage) +

Usage:

+
    +# for usage in iter(item.usage) do + $(li)
    $(ldoc.prettify(usage))
    $(il) +# end -- for +
+# end -- if usage + +
+# end -- for items +
+# end -- for kinds + +# else -- if module; project-level contents + +# if ldoc.description then +

$(M(ldoc.description,nil))

+# end +# if ldoc.full_description then +

$(M(ldoc.full_description,nil))

+# end + +# for kind, mods in ldoc.kinds() do +

$(kind)

+# kind = kind:lower() + +# for m in mods() do + + + + +# end -- for modules +
$(m.name)$(M(ldoc.strip_header(m.summary),m))
+# end -- for kinds +# end -- if module + +
+
+
+generated by LDoc $(ldoc.version) +Last updated $(ldoc.updatetime) +
+
+ +