awesomewm-mirrors
/
awesome
mirror of https://github.com/awesomeWM/awesome.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
awesome/docs/ldoc.ltp

660 lines
21 KiB
Plaintext
Raw Normal View History

ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
ldoc.ltp: improve HTML title
2019-01-04 14:25:36 +01:00
# local title = module and ldoc.module_typename(module).." "..module.name.." - "..ldoc.title or ldoc.title
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
<html>
<head>
ldoc.ltp: improve HTML title
2019-01-04 14:25:36 +01:00
<meta http-equiv="Content-Type" content="text/html; charset=$(ldoc.doc_charset)"/>
<title>$(title)</title>
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
<link rel="stylesheet" href="$(ldoc.css)" type="text/css" />
# if ldoc.custom_css then -- add custom CSS file if configured.
<link rel="stylesheet" href="$(ldoc.custom_css)" type="text/css" />
# end
doc: Hide the newly auto-generated content by default. First of all, yes, JavaScript in the doc. I don't like this either. The reason is that the new sections are super useful *when you need them*. However, in practice, that's rare. So better not make the signal to noise ratio worst. Future commit will introduce an auto-generated summary of what's hidden.
2019-11-25 05:59:27 +01:00
<script>
function show_extra(id) {
doc: Add a summary next to the property/method title.
2019-11-28 09:04:26 +01:00
var cur = document.getElementById("item"+id).className
doc: Hide the newly auto-generated content by default. First of all, yes, JavaScript in the doc. I don't like this either. The reason is that the new sections are super useful *when you need them*. However, in practice, that's rare. So better not make the signal to noise ratio worst. Future commit will introduce an auto-generated summary of what's hidden.
2019-11-25 05:59:27 +01:00
doc: Add a summary next to the property/method title.
2019-11-28 09:04:26 +01:00
if (cur == "hide_extra") {
document.getElementById("item"+id).className = "show_more"
document.getElementById("button"+id).className = "hide_extra"
}
doc: Hide the newly auto-generated content by default. First of all, yes, JavaScript in the doc. I don't like this either. The reason is that the new sections are super useful *when you need them*. However, in practice, that's rare. So better not make the signal to noise ratio worst. Future commit will introduce an auto-generated summary of what's hidden.
2019-11-25 05:59:27 +01:00
}
</script>
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
</head>
<body>
<div id="container">
<div id="main">
# local no_spaces = ldoc.no_spaces
# local use_li = ldoc.use_li
# local display_name = ldoc.display_name
# local iter = ldoc.modules.iter
doc: Fix another CMake related encoding problem.
2021-12-13 23:19:15 +01:00
# local function un_cmake(s) return s:gsub("&#59", ";"):gsub("&#34", '"'):gsub('&amp;#34', '"') end
doc: Fix the rendering of double quotes and semicolons CMake uses quotes and semicolon in its internal list datatype. Previously, all double quotes were converted to single quotes to avoid this problem. Semicolors were interpreted as newlines in ldoc. With this commit, both of them render fine. This was required because a new example uses CSS and XML where those symbols have a specific meanning.
2021-09-12 03:59:46 +02:00
# local function M(txt,item) return ldoc.markup(txt and un_cmake(txt) or nil,item,ldoc.plain) end
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# local nowrap = ldoc.wrap and '' or 'nowrap'
doc: Fix index links. (#2803) Fixes #2797
2019-06-28 15:34:32 +02:00
# local html_space = function(s) return s:gsub(" ", "%%20") end
doc: Prevent ldoc from generating URLs with spaces. For dubious reasons, ldoc uses the human readable name for the URLs instead of the machine readable one. If the name has multiple words, this causes the URLs to have spaces or %20 in them. This commits remove all spaces from the "kinds" and then use `:gsub()` in the template to convert underscores to spaces. **WARNING** This breaks all URLs again. But this is necessary to prevent broken links when the user paste them with spaces instead of %20.
2019-07-09 22:28:42 +02:00
# local no_underscores = function(s) return s:gsub("_", " ") end
doc: Improve the "See also" section. Now display: * The description summary. * The item kind. * The module name (if non-local).
2021-12-14 21:14:32 +01:00
# local get_item = function(mod, name) for item in iter(mod.items) do if item.name == name then return item end end; return name == "" and mod or nil end
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
doc(@supermodule;ldoc.ltp): Draw hierarchy tree This commit adds a new ldoc custom tag `@supermodule`. It has to be used at the module level. It should refer to the module supermodules. This tag can be used multiple time by the same module, but we ignore other calls (for now?) as (AFAIK) we only use one way inheritance. This tag is used in the ldoc template to find modules hierarchy and draw the inheritance tree. It makes it easy to find and navigate to parents modules.
2021-03-14 15:40:48 +01:00
# --------- modules hierarchy -------------
# local hierarchy = {}
# local curr = module
# while curr do
# hierarchy[#hierarchy + 1] = curr
# -- no need to do anything more if there is no explicite @supermodule
# if not curr.tags.supermodule then break end
# local super = curr.tags.supermodule[1] -- only consider one way inheritance
# local found = false
# for kind, mods, type in ldoc.kinds() do
# for mod in mods() do
# local name = display_name(mod)
# if name == super then
# curr = mod
# found = true
# end
# if found then break end
# end
# if found then break end
# end
# if not found then curr = nil end
# end
doc(@supermodule;ldoc.ltp): Find inherited members This commit uses the `@supermodule` tag to recursively find all the properties from supermodules and add them to the current module documentation.
2021-03-15 18:32:47 +01:00
# --------- merge modules content with supermodules -------------
# local all_module_kinds = {}
# if module then
# for kind,items in module.kinds() do
# local myitems = {}
# for item in items() do
doc(@hidden;ldoc.ltp): Add ldoc tag to hide item Add a new ldoc tag `@hidden`. This tag allows us to keep documentation for magic methods (e.g. `wibox.widget.base:get_visible`) but prevent it from being part of the documentation used by final users.
2021-03-28 18:19:08 +02:00
# myitems[#myitems + 1] = item
doc(@supermodule;ldoc.ltp): Find inherited members This commit uses the `@supermodule` tag to recursively find all the properties from supermodules and add them to the current module documentation.
2021-03-15 18:32:47 +01:00
# end
# all_module_kinds[#all_module_kinds + 1] = { kind = kind, items = myitems }
# end
# local filtered_kinds = { "Constructors", "Static module functions",
# "Functions", "Methods", "lib.gears.object.properties Functions" }
# for supermodule in iter(hierarchy) do
# for kind,items in supermodule.kinds() do
# local ignored = false
# for _,filtered in ldoc.pairs(filtered_kinds) do
# if kind == filtered then
# ignored = true
# break
# end
# end
# if not ignored then
# local curr_kind = nil
# for k in iter(all_module_kinds) do
# if k.kind == kind then
# curr_kind = k
# break
# end
# end
# if not curr_kind then
# curr_kind = { kind = kind, items = {} }
# all_module_kinds[#all_module_kinds + 1] = curr_kind
# end
# for item in items() do
# local tobeadded = true
# for i in iter(curr_kind.items) do
fix(ldoc.ltp): Identify inherited items by name
2021-03-27 20:05:52 +01:00
# if item.name == i.name then
doc(@supermodule;ldoc.ltp): Find inherited members This commit uses the `@supermodule` tag to recursively find all the properties from supermodules and add them to the current module documentation.
2021-03-15 18:32:47 +01:00
# tobeadded = false
# break
# end
# end
# if tobeadded then
# item.inherited = true -- force inherited status
# curr_kind.items[#curr_kind.items + 1] = item
# end
# end
# end
# end
# end
# end
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
<!-- Menu -->
<div id="navigation">
<h1>$(ldoc.project)</h1>
# if not ldoc.single and module then -- reference back to project index
<ul>
<li><a href="../$(ldoc.output).html">Index</a></li>
</ul>
# end
# --------- contents of module -------------
# if module and not ldoc.no_summary and #module.items > 0 then
<h2>Contents</h2>
<ul>
doc(@supermodule;ldoc.ltp): Find inherited members This commit uses the `@supermodule` tag to recursively find all the properties from supermodules and add them to the current module documentation.
2021-03-15 18:32:47 +01:00
# for k in iter(all_module_kinds) do
# local kind = k.kind
doc: Modify the template to allow merging sections. It might not be the most pretty of change, but it works. With this change, it is possible to have multiple "things" in the "same" section having the "same" name. This allows for C/C++ style functions with the same name but different signatures. Lua doesn't handle this well, so it should usually be avoided. However, constructors might be a valid exception. Most older widget (and object) constructors have multiple random argument while newer one use `args`. Deprecating the old ones for the sake of standardization might be a bit too much for users upgrading from v3.5. Given the only reason all of those deprecation would happen is because "its pretty that way", then lets allow 2 constructors and avoid outrage.
2019-10-27 20:39:23 +01:00
# if not kind:match("^ldoc_skip") then
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
<li><a href="#$(no_spaces(kind))">$(kind)</a></li>
# end
doc: Modify the template to allow merging sections. It might not be the most pretty of change, but it works. With this change, it is possible to have multiple "things" in the "same" section having the "same" name. This allows for C/C++ style functions with the same name but different signatures. Lua doesn't handle this well, so it should usually be avoided. However, constructors might be a valid exception. Most older widget (and object) constructors have multiple random argument while newer one use `args`. Deprecating the old ones for the sake of standardization might be a bit too much for users upgrading from v3.5. Given the only reason all of those deprecation would happen is because "its pretty that way", then lets allow 2 constructors and avoid outrage.
2019-10-27 20:39:23 +01:00
# end
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
</ul>
# end
# if ldoc.no_summary and module and not ldoc.one then -- bang out the functions on the side
# for kind, items in module.kinds() do
doc: Modify the template to allow merging sections. It might not be the most pretty of change, but it works. With this change, it is possible to have multiple "things" in the "same" section having the "same" name. This allows for C/C++ style functions with the same name but different signatures. Lua doesn't handle this well, so it should usually be avoided. However, constructors might be a valid exception. Most older widget (and object) constructors have multiple random argument while newer one use `args`. Deprecating the old ones for the sake of standardization might be a bit too much for users upgrading from v3.5. Given the only reason all of those deprecation would happen is because "its pretty that way", then lets allow 2 constructors and avoid outrage.
2019-10-27 20:39:23 +01:00
# if not kind:match("^ldoc_skip") then
doc: Replace the function argument rendering. This is an attempt at solving several problems reported by novice users. The old rendering was very compact and quite fine once you got used to its, ..., "conventions". But it was also sometime rather hard to read. First of all, it abused bold and italic. It also "merged" optional parameters and parameters with default content. It got worst when the documentation was spread over mutiple lines. For property types and constructors with large number of parameters, it was also quite unreadable. The new representation, while far from perfect, is less dense and more explicit. It has a separate column for "optional" using the new "metadata chip" documentation concept. It is also an aligned table and correctly renders multi-line documentation. Finally, it adds a "note" message when the named parameter convention is used. This way the users looking at the examples will be less confused.
2021-12-17 22:34:49 +01:00
<h2>$(kind)</h2>
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
<ul class="nowrap">
doc: Modify the template to allow merging sections. It might not be the most pretty of change, but it works. With this change, it is possible to have multiple "things" in the "same" section having the "same" name. This allows for C/C++ style functions with the same name but different signatures. Lua doesn't handle this well, so it should usually be avoided. However, constructors might be a valid exception. Most older widget (and object) constructors have multiple random argument while newer one use `args`. Deprecating the old ones for the sake of standardization might be a bit too much for users upgrading from v3.5. Given the only reason all of those deprecation would happen is because "its pretty that way", then lets allow 2 constructors and avoid outrage.
2019-10-27 20:39:23 +01:00
# end
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# for item in items() do
<li><a href="#$(item.name)">$(display_name(item))</a></li>
# end
doc: Modify the template to allow merging sections. It might not be the most pretty of change, but it works. With this change, it is possible to have multiple "things" in the "same" section having the "same" name. This allows for C/C++ style functions with the same name but different signatures. Lua doesn't handle this well, so it should usually be avoided. However, constructors might be a valid exception. Most older widget (and object) constructors have multiple random argument while newer one use `args`. Deprecating the old ones for the sake of standardization might be a bit too much for users upgrading from v3.5. Given the only reason all of those deprecation would happen is because "its pretty that way", then lets allow 2 constructors and avoid outrage.
2019-10-27 20:39:23 +01:00
# if not kind:match("^ldoc_skip") then
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
</ul>
# end
# end
doc: Modify the template to allow merging sections. It might not be the most pretty of change, but it works. With this change, it is possible to have multiple "things" in the "same" section having the "same" name. This allows for C/C++ style functions with the same name but different signatures. Lua doesn't handle this well, so it should usually be avoided. However, constructors might be a valid exception. Most older widget (and object) constructors have multiple random argument while newer one use `args`. Deprecating the old ones for the sake of standardization might be a bit too much for users upgrading from v3.5. Given the only reason all of those deprecation would happen is because "its pretty that way", then lets allow 2 constructors and avoid outrage.
2019-10-27 20:39:23 +01:00
# end
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# -------- contents of project ----------
# local this_mod = module and module.name
# for kind, mods, type in ldoc.kinds() do
# if ldoc.allowed_in_contents(type,module) then
doc: Prevent ldoc from generating URLs with spaces. For dubious reasons, ldoc uses the human readable name for the URLs instead of the machine readable one. If the name has multiple words, this causes the URLs to have spaces or %20 in them. This commits remove all spaces from the "kinds" and then use `:gsub()` in the template to convert underscores to spaces. **WARNING** This breaks all URLs again. But this is necessary to prevent broken links when the user paste them with spaces instead of %20.
2019-07-09 22:28:42 +02:00
<h2>$(no_underscores(kind))</h2>
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
<ul class="$(kind=='Topics' and '' or 'nowrap')">
# for mod in mods() do local name = display_name(mod)
# if mod.name == this_mod then
<li><strong>$(name)</strong></li>
# else
<li><a href="$(ldoc.ref_to_module(mod))">$(name)</a></li>
# end
# end
# end
</ul>
# end
</div>
<div id="content">
# if ldoc.body then -- verbatim HTML as contents; 'non-code' entries
doc: Fix another CMake related encoding problem.
2021-12-13 23:19:15 +01:00
$(un_cmake(ldoc.body))
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# elseif module then -- module documentation
doc: Hardcode the header instead of using "machine readable". "classmod" is not useful for a humain.
2019-06-08 01:20:48 +02:00
<h1>Module: <code>$(module.name)</code></h1>
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
<p>$(M(module.summary,module))</p>
<p>$(M(module.description,module))</p>
doc(ltp): Implement module `extra-header` section Co-authored-by: Lucas Schwiderski <lucas@lschwiderski.de> Co-authored-by: Aire-One <Aire-One@users.noreply.github.com>
2021-03-29 09:40:16 +02:00
# if module.usage then
# local li,il = use_li(module.usage)
<h3>Usage:</h3>
<ul>
# for usage in iter(module.usage) do
doc: Fix the rendering of double quotes and semicolons CMake uses quotes and semicolon in its internal list datatype. Previously, all double quotes were converted to single quotes to avoid this problem. Semicolors were interpreted as newlines in ldoc. With this commit, both of them render fine. This was required because a new example uses CSS and XML where those symbols have a specific meanning.
2021-09-12 03:59:46 +02:00
$(li)<pre class="example">$(ldoc.escape(un_cmake(usage)))</pre>$(il)
doc(ltp): Implement module `extra-header` section Co-authored-by: Lucas Schwiderski <lucas@lschwiderski.de> Co-authored-by: Aire-One <Aire-One@users.noreply.github.com>
2021-03-29 09:40:16 +02:00
# end -- for
</ul>
# end -- if usage
fix(ldoc.ltp): extra-header tag arrangement (#3318)
2021-04-05 18:42:15 +02:00
<div class="extra-header">
# if module.tags.supermodule then
doc(ltp): Implement module `extra-header` section Co-authored-by: Lucas Schwiderski <lucas@lschwiderski.de> Co-authored-by: Aire-One <Aire-One@users.noreply.github.com>
2021-03-29 09:40:16 +02:00
<div class="extra-header__section">
doc(@supermodule;ldoc.ltp): Draw hierarchy tree This commit adds a new ldoc custom tag `@supermodule`. It has to be used at the module level. It should refer to the module supermodules. This tag can be used multiple time by the same module, but we ignore other calls (for now?) as (AFAIK) we only use one way inheritance. This tag is used in the ldoc template to find modules hierarchy and draw the inheritance tree. It makes it easy to find and navigate to parents modules.
2021-03-14 15:40:48 +01:00
<h3>Class Hierarchy</h3>
<div class="inheritance">
# local function draw_hierary_recursifly(i)
doc(ltp): Implement module `extra-header` section Co-authored-by: Lucas Schwiderski <lucas@lschwiderski.de> Co-authored-by: Aire-One <Aire-One@users.noreply.github.com>
2021-03-29 09:40:16 +02:00
# local is_root_level = (i == #hierarchy)
<ul class="inheritance__level $(is_root_level and 'inheritance__level--root' or '')">
<li class="inheritance__level__node $(is_root_level and 'inheritance__level__node--root' or '')">
doc(@supermodule;ldoc.ltp): Draw hierarchy tree This commit adds a new ldoc custom tag `@supermodule`. It has to be used at the module level. It should refer to the module supermodules. This tag can be used multiple time by the same module, but we ignore other calls (for now?) as (AFAIK) we only use one way inheritance. This tag is used in the ldoc template to find modules hierarchy and draw the inheritance tree. It makes it easy to find and navigate to parents modules.
2021-03-14 15:40:48 +01:00
# local mod = hierarchy[i]
# local name = display_name(hierarchy[i])
# if mod == module then
<strong>$(name)</strong>
# else
<a href="$(ldoc.ref_to_module(mod))">$(name)</a>
# end
</li>
# if i > 1 then
<li>
# draw_hierary_recursifly(i - 1)
</li>
# end
</ul>
fix(ldoc.ltp): extra-header tag arrangement (#3318)
2021-04-05 18:42:15 +02:00
# end -- function draw_hierary_recursifly
doc(@supermodule;ldoc.ltp): Draw hierarchy tree This commit adds a new ldoc custom tag `@supermodule`. It has to be used at the module level. It should refer to the module supermodules. This tag can be used multiple time by the same module, but we ignore other calls (for now?) as (AFAIK) we only use one way inheritance. This tag is used in the ldoc template to find modules hierarchy and draw the inheritance tree. It makes it easy to find and navigate to parents modules.
2021-03-14 15:40:48 +01:00
# draw_hierary_recursifly(#hierarchy)
</div>
fix(ldoc.ltp): extra-header tag arrangement (#3318)
2021-04-05 18:42:15 +02:00
</div>
# end -- module.tags.supermodule
doc(@supermodule;ldoc.ltp): Draw hierarchy tree This commit adds a new ldoc custom tag `@supermodule`. It has to be used at the module level. It should refer to the module supermodules. This tag can be used multiple time by the same module, but we ignore other calls (for now?) as (AFAIK) we only use one way inheritance. This tag is used in the ldoc template to find modules hierarchy and draw the inheritance tree. It makes it easy to find and navigate to parents modules.
2021-03-14 15:40:48 +01:00
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# if module.tags.include then
$(M(ldoc.include_file(module.tags.include)))
# end
fix(ldoc.ltp): extra-header tag arrangement (#3318)
2021-04-05 18:42:15 +02:00
doc(ltp): Implement module `extra-header` section Co-authored-by: Lucas Schwiderski <lucas@lschwiderski.de> Co-authored-by: Aire-One <Aire-One@users.noreply.github.com>
2021-03-29 09:40:16 +02:00
# if module.info then
<div class="extra-header__section">
<h3>Info:</h3>
<ul>
# for tag, value in module.info:iter() do
doc(ltp) Change author mention
2021-06-12 17:49:42 +02:00
# if tag == 'Author' then
<li>
<strong>Originally authored by</strong>: $(M(value,module))<br />
<small>(Full contributors list available on
<a href="https://github.com/awesomeWM/awesome/graphs/contributors">
our github project)
</a></small>
</li>
# else
<li><strong>$(tag)</strong>: $(M(value,module))</li>
# end
doc(ltp): Implement module `extra-header` section Co-authored-by: Lucas Schwiderski <lucas@lschwiderski.de> Co-authored-by: Aire-One <Aire-One@users.noreply.github.com>
2021-03-29 09:40:16 +02:00
# end
</ul>
</div>
# end -- if module.info
fix(ldoc.ltp): extra-header tag arrangement (#3318)
2021-04-05 18:42:15 +02:00
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# if module.see then
doc(ltp): Implement module `extra-header` section Co-authored-by: Lucas Schwiderski <lucas@lschwiderski.de> Co-authored-by: Aire-One <Aire-One@users.noreply.github.com>
2021-03-29 09:40:16 +02:00
<div class="extra-header__section">
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# local li,il = use_li(module.see)
fix(ldoc.ltp): extra-header tag arrangement (#3318)
2021-04-05 18:42:15 +02:00
# local list_or_p =(#module.see > 1) and 'ul' or 'p'
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
<h3>See also:</h3>
fix(ldoc.ltp): extra-header tag arrangement (#3318)
2021-04-05 18:42:15 +02:00
<$(list_or_p)>
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# for see in iter(module.see) do
doc: Improve the "See also" section. Now display: * The description summary. * The item kind. * The module name (if non-local).
2021-12-14 21:14:32 +01:00
$(li)<a href="$(ldoc.href(see))">$(see.label) BOB</a>$(il)
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# end -- for
fix(ldoc.ltp): extra-header tag arrangement (#3318)
2021-04-05 18:42:15 +02:00
</$(list_or_p)>
doc(ltp): Implement module `extra-header` section Co-authored-by: Lucas Schwiderski <lucas@lschwiderski.de> Co-authored-by: Aire-One <Aire-One@users.noreply.github.com>
2021-03-29 09:40:16 +02:00
</div>
fix(ldoc.ltp): extra-header tag arrangement (#3318)
2021-04-05 18:42:15 +02:00
# end -- if module.see
doc(ltp): Implement module `extra-header` section Co-authored-by: Lucas Schwiderski <lucas@lschwiderski.de> Co-authored-by: Aire-One <Aire-One@users.noreply.github.com>
2021-03-29 09:40:16 +02:00
</div>
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# if not ldoc.no_summary then
# -- bang out the tables of item types for this module (e.g Functions, Tables, etc)
doc: Modify the template to allow merging sections. It might not be the most pretty of change, but it works. With this change, it is possible to have multiple "things" in the "same" section having the "same" name. This allows for C/C++ style functions with the same name but different signatures. Lua doesn't handle this well, so it should usually be avoided. However, constructors might be a valid exception. Most older widget (and object) constructors have multiple random argument while newer one use `args`. Deprecating the old ones for the sake of standardization might be a bit too much for users upgrading from v3.5. Given the only reason all of those deprecation would happen is because "its pretty that way", then lets allow 2 constructors and avoid outrage.
2019-10-27 20:39:23 +01:00
# local last_kind = ""
doc(@supermodule;ldoc.ltp): Find inherited members This commit uses the `@supermodule` tag to recursively find all the properties from supermodules and add them to the current module documentation.
2021-03-15 18:32:47 +01:00
# for k in iter(all_module_kinds) do
# local kind = k.kind
doc: Modify the template to allow merging sections. It might not be the most pretty of change, but it works. With this change, it is possible to have multiple "things" in the "same" section having the "same" name. This allows for C/C++ style functions with the same name but different signatures. Lua doesn't handle this well, so it should usually be avoided. However, constructors might be a valid exception. Most older widget (and object) constructors have multiple random argument while newer one use `args`. Deprecating the old ones for the sake of standardization might be a bit too much for users upgrading from v3.5. Given the only reason all of those deprecation would happen is because "its pretty that way", then lets allow 2 constructors and avoid outrage.
2019-10-27 20:39:23 +01:00
# if not kind:match("^ldoc_skip") then
# if last_kind ~= "" then
</table>
# end
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
<h2><a href="#$(no_spaces(kind))">$(kind)</a></h2>
<table class="function_list">
doc: Modify the template to allow merging sections. It might not be the most pretty of change, but it works. With this change, it is possible to have multiple "things" in the "same" section having the "same" name. This allows for C/C++ style functions with the same name but different signatures. Lua doesn't handle this well, so it should usually be avoided. However, constructors might be a valid exception. Most older widget (and object) constructors have multiple random argument while newer one use `args`. Deprecating the old ones for the sake of standardization might be a bit too much for users upgrading from v3.5. Given the only reason all of those deprecation would happen is because "its pretty that way", then lets allow 2 constructors and avoid outrage.
2019-10-27 20:39:23 +01:00
# end
doc(@hidden;ldoc.ltp): Add ldoc tag to hide item Add a new ldoc tag `@hidden`. This tag allows us to keep documentation for magic methods (e.g. `wibox.widget.base:get_visible`) but prevent it from being part of the documentation used by final users.
2021-03-28 18:19:08 +02:00
# for item in iter(k.items) do if not item.tags.hidden then
doc: Add support for property types to ldoc. Rather that abusing of how the arguments are displayed to convey the type, add native support. It still uses the @param for the doc, so this doesn't cause a million little noisy changes, but the rendered HTML now have a real section for the type. This is added to both the summary and the expanded description. Additionally, if the type has a description string, a second is added.
2019-06-08 04:53:36 +02:00
# local dn = display_name(item)
fix(ldoc.ltp): item.inherited can be wrongly true For some even more strange reasons than commit 047729ae1, it seems we can also have the error that `item.inherited` can be sets to `true` on items that are not inherited... I just had this issue with `wibox.widget.imagebox` where properties were marked as inherited from `wibox.widget.imagebox`. Best way to fix it is to only trust the check on `item.baseclass`, and completly dismiss its `inherited` property.
2021-03-28 18:47:56 +02:00
# local inherited = (item.baseclass ~= module.name)
doc: Add support for property types to ldoc. Rather that abusing of how the arguments are displayed to convey the type, add native support. It still uses the @param for the doc, so this doesn't cause a million little noisy changes, but the rendered HTML now have a real section for the type. This is added to both the summary and the expanded description. Additionally, if the type has a description string, a second is added.
2019-06-08 04:53:36 +02:00
# if item.sanitize_type then item.sanitize_type(item, ldoc) end
doc: Add a mild hover color change to the summary. It is hard know to which row a "chip" like inherited belongs to. This fixes it for mouse users. I also tried using alternate row colors, but our colors are so "light" that there wasn't any good candidate between "white" and the <body> background color.
2021-12-13 20:33:19 +01:00
<tr class="summary_row">
doc: Use a more compact rendering for method return types.
2020-03-01 03:16:11 +01:00
# if item.display_type and not item.compact_signature then
doc: Do not mix spaces and tabs for indentation in the generated HTML.
2019-07-09 23:00:20 +02:00
<td class="shortname" $(nowrap)><a href="#$(item.name)">$(dn)</a></td>
<td class="summarytype" nowrap>$(item.display_type)</td>
doc: Add support for property types to ldoc. Rather that abusing of how the arguments are displayed to convey the type, add native support. It still uses the @param for the doc, so this doesn't cause a million little noisy changes, but the rendered HTML now have a real section for the type. This is added to both the summary and the expanded description. Additionally, if the type has a description string, a second is added.
2019-06-08 04:53:36 +02:00
# else
doc: Use a more compact rendering for method return types.
2020-03-01 03:16:11 +01:00
<td class="name" $(nowrap)>
<a href="#$(item.name)">$(dn)</a>
# if item.display_type and item.compact_signature then
<span class="summarytype">$(item.display_type)</span>
# end
</td>
doc: Add support for property types to ldoc. Rather that abusing of how the arguments are displayed to convey the type, add native support. It still uses the @param for the doc, so this doesn't cause a million little noisy changes, but the rendered HTML now have a real section for the type. This is added to both the summary and the expanded description. Additionally, if the type has a description string, a second is added.
2019-06-08 04:53:36 +02:00
# end
doc: Merge the Inherited/Deprecated/Readonly tag style. They are on the right like Inherited, but use the "chip" style of ReadOnly.
2021-12-13 20:04:32 +01:00
<td class="summary">
Adding readonly tag to the summary
2021-10-27 00:27:41 +02:00
$(M(item.summary,item))
doc: Merge the Inherited/Deprecated/Readonly tag style. They are on the right like Inherited, but use the "chip" style of ReadOnly.
2021-12-13 20:04:32 +01:00
</td>
<td class="baseclass" nowrap>
# if item.tags.is_deprecated then
<span class="chips">Deprecated</span>
# end
Adding readonly tag to the summary
2021-10-27 00:27:41 +02:00
# if item.tags.readonly then
doc: Merge the Inherited/Deprecated/Readonly tag style. They are on the right like Inherited, but use the "chip" style of ReadOnly.
2021-12-13 20:04:32 +01:00
<span class="chips">Read only</span>
Adding readonly tag to the summary
2021-10-27 00:27:41 +02:00
# end
fix(ldoc.ltp): item.inherited can be wrongly false For some reasons, sometime `item.inherited` is `false` even if the item was added to the `all_module_kinds` table by the "hierarchy lookup" for-loop, and we already force the `inherited` property to be sets to `true` at this moment. With this commit, we add a second fail-check condition based on the `item.baseclass` property to determine if the item is inherited or not when we do the render.
2021-03-27 15:42:20 +01:00
# if inherited then
doc: Merge the Inherited/Deprecated/Readonly tag style. They are on the right like Inherited, but use the "chip" style of ReadOnly.
2021-12-13 20:04:32 +01:00
<span class="chips">Inherited from $(item.baseclass)</span>
Add ldoc tags for inherited members. * Add `@inheritedproperty`, `@inheritedmethod` and `@inheritedsignal` ldoc tags to specify inherited members in the documentation, * These new tags create their own section in the rendered documentation, * Implemente these tags for `docs/common/object.ldoc` and `docs/common/widget.ldoc`.
2019-11-23 13:58:47 +01:00
# end
doc: Merge the Inherited/Deprecated/Readonly tag style. They are on the right like Inherited, but use the "chip" style of ReadOnly.
2021-12-13 20:04:32 +01:00
</td>
doc: Do not mix spaces and tabs for indentation in the generated HTML.
2019-07-09 23:00:20 +02:00
</tr>
doc(@hidden;ldoc.ltp): Add ldoc tag to hide item Add a new ldoc tag `@hidden`. This tag allows us to keep documentation for magic methods (e.g. `wibox.widget.base:get_visible`) but prevent it from being part of the documentation used by final users.
2021-03-28 18:19:08 +02:00
# end end -- for items
doc: Modify the template to allow merging sections. It might not be the most pretty of change, but it works. With this change, it is possible to have multiple "things" in the "same" section having the "same" name. This allows for C/C++ style functions with the same name but different signatures. Lua doesn't handle this well, so it should usually be avoided. However, constructors might be a valid exception. Most older widget (and object) constructors have multiple random argument while newer one use `args`. Deprecating the old ones for the sake of standardization might be a bit too much for users upgrading from v3.5. Given the only reason all of those deprecation would happen is because "its pretty that way", then lets allow 2 constructors and avoid outrage.
2019-10-27 20:39:23 +01:00
# last_kind = kind
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
#end -- for kinds
doc: Modify the template to allow merging sections. It might not be the most pretty of change, but it works. With this change, it is possible to have multiple "things" in the "same" section having the "same" name. This allows for C/C++ style functions with the same name but different signatures. Lua doesn't handle this well, so it should usually be avoided. However, constructors might be a valid exception. Most older widget (and object) constructors have multiple random argument while newer one use `args`. Deprecating the old ones for the sake of standardization might be a bit too much for users upgrading from v3.5. Given the only reason all of those deprecation would happen is because "its pretty that way", then lets allow 2 constructors and avoid outrage.
2019-10-27 20:39:23 +01:00
</table>
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
<br/>
<br/>
#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
doc: Modify the template to allow merging sections. It might not be the most pretty of change, but it works. With this change, it is possible to have multiple "things" in the "same" section having the "same" name. This allows for C/C++ style functions with the same name but different signatures. Lua doesn't handle this well, so it should usually be avoided. However, constructors might be a valid exception. Most older widget (and object) constructors have multiple random argument while newer one use `args`. Deprecating the old ones for the sake of standardization might be a bit too much for users upgrading from v3.5. Given the only reason all of those deprecation would happen is because "its pretty that way", then lets allow 2 constructors and avoid outrage.
2019-10-27 20:39:23 +01:00
# local show_parms, last_kind = show_return, ""
doc(@supermodule;ldoc.ltp): Find inherited members This commit uses the `@supermodule` tag to recursively find all the properties from supermodules and add them to the current module documentation.
2021-03-15 18:32:47 +01:00
# for k in iter(all_module_kinds) do
# local kind = k.kind
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# local kitem = module.kinds:get_item(kind)
# local has_description = kitem and ldoc.descript(kitem) ~= ""
doc: Modify the template to allow merging sections. It might not be the most pretty of change, but it works. With this change, it is possible to have multiple "things" in the "same" section having the "same" name. This allows for C/C++ style functions with the same name but different signatures. Lua doesn't handle this well, so it should usually be avoided. However, constructors might be a valid exception. Most older widget (and object) constructors have multiple random argument while newer one use `args`. Deprecating the old ones for the sake of standardization might be a bit too much for users upgrading from v3.5. Given the only reason all of those deprecation would happen is because "its pretty that way", then lets allow 2 constructors and avoid outrage.
2019-10-27 20:39:23 +01:00
# if not kind:match("^ldoc_skip") then
# if last_kind ~= "" then
</dl>
# end
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
<h2 class="section-header $(has_description and 'has-description')"><a name="$(no_spaces(kind))"></a>$(kind)</h2>
doc: Modify the template to allow merging sections. It might not be the most pretty of change, but it works. With this change, it is possible to have multiple "things" in the "same" section having the "same" name. This allows for C/C++ style functions with the same name but different signatures. Lua doesn't handle this well, so it should usually be avoided. However, constructors might be a valid exception. Most older widget (and object) constructors have multiple random argument while newer one use `args`. Deprecating the old ones for the sake of standardization might be a bit too much for users upgrading from v3.5. Given the only reason all of those deprecation would happen is because "its pretty that way", then lets allow 2 constructors and avoid outrage.
2019-10-27 20:39:23 +01:00
# end
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
$(M(module.kinds:get_section_description(kind),nil))
# if kitem then
# if has_description then
<div class="section-description">
$(M(ldoc.descript(kitem),kitem))
</div>
# end
# if kitem.usage then
<h3>Usage:</h3>
doc: Fix the rendering of double quotes and semicolons CMake uses quotes and semicolon in its internal list datatype. Previously, all double quotes were converted to single quotes to avoid this problem. Semicolors were interpreted as newlines in ldoc. With this commit, both of them render fine. This was required because a new example uses CSS and XML where those symbols have a specific meanning.
2021-09-12 03:59:46 +02:00
<pre class="example">$(ldoc.prettify(un_cmake(kitem.usage[1])))</pre>
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# end
# end
doc: Modify the template to allow merging sections. It might not be the most pretty of change, but it works. With this change, it is possible to have multiple "things" in the "same" section having the "same" name. This allows for C/C++ style functions with the same name but different signatures. Lua doesn't handle this well, so it should usually be avoided. However, constructors might be a valid exception. Most older widget (and object) constructors have multiple random argument while newer one use `args`. Deprecating the old ones for the sake of standardization might be a bit too much for users upgrading from v3.5. Given the only reason all of those deprecation would happen is because "its pretty that way", then lets allow 2 constructors and avoid outrage.
2019-10-27 20:39:23 +01:00
# if not kind:match("^ldoc_skip") then
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
<dl class="function">
doc: Modify the template to allow merging sections. It might not be the most pretty of change, but it works. With this change, it is possible to have multiple "things" in the "same" section having the "same" name. This allows for C/C++ style functions with the same name but different signatures. Lua doesn't handle this well, so it should usually be avoided. However, constructors might be a valid exception. Most older widget (and object) constructors have multiple random argument while newer one use `args`. Deprecating the old ones for the sake of standardization might be a bit too much for users upgrading from v3.5. Given the only reason all of those deprecation would happen is because "its pretty that way", then lets allow 2 constructors and avoid outrage.
2019-10-27 20:39:23 +01:00
# end
doc(@hidden;ldoc.ltp): Add ldoc tag to hide item Add a new ldoc tag `@hidden`. This tag allows us to keep documentation for magic methods (e.g. `wibox.widget.base:get_visible`) but prevent it from being part of the documentation used by final users.
2021-03-28 18:19:08 +02:00
# for item in iter(k.items) do if not item.tags.hidden then
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
<dt>
add(ltp) .function anchor copy link to clipboard
2022-01-02 17:12:38 +01:00
<a class="copy-link js-copy-link" name="$(item.name)" href="#$(item.name)">&#128279;</a>
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
<strong>$(display_name(item))</strong>
Add ldoc tags for inherited members. * Add `@inheritedproperty`, `@inheritedmethod` and `@inheritedsignal` ldoc tags to specify inherited members in the documentation, * These new tags create their own section in the rendered documentation, * Implemente these tags for `docs/common/object.ldoc` and `docs/common/widget.ldoc`.
2019-11-23 13:58:47 +01:00
# if item.display_inheritance then
<span class="inheritance">
&middot Inherited from
<a href="$(item.display_inheritance)">$(item.display_inheritance)</a>
doc: Add a summary next to the property/method title.
2019-11-28 09:04:26 +01:00
</span>
# end -- display_inheritance
doc: Add support for property types to ldoc. Rather that abusing of how the arguments are displayed to convey the type, add native support. It still uses the @param for the doc, so this doesn't cause a million little noisy changes, but the rendered HTML now have a real section for the type. This is added to both the summary and the expanded description. Additionally, if the type has a description string, a second is added.
2019-06-08 04:53:36 +02:00
# if item.display_type then
doc: Do not add parentheses arpund property types. They provide no value.
2020-03-01 03:08:42 +01:00
<span class="proptype">$(item.display_type)</span>
doc: Add support for property types to ldoc. Rather that abusing of how the arguments are displayed to convey the type, add native support. It still uses the @param for the doc, so this doesn't cause a million little noisy changes, but the rendered HTML now have a real section for the type. This is added to both the summary and the expanded description. Additionally, if the type has a description string, a second is added.
2019-06-08 04:53:36 +02:00
# end
doc: Add a summary next to the property/method title.
2019-11-28 09:04:26 +01:00
<span class="baseclass" $(nowrap)>
fix(ldoc.ltp): item.inherited can be wrongly true For some even more strange reasons than commit 047729ae1, it seems we can also have the error that `item.inherited` can be sets to `true` on items that are not inherited... I just had this issue with `wibox.widget.imagebox` where properties were marked as inherited from `wibox.widget.imagebox`. Best way to fix it is to only trust the check on `item.baseclass`, and completly dismiss its `inherited` property.
2021-03-28 18:47:56 +02:00
# if item.baseclass ~= module.name then
fix(ldoc.ltp): item.inherited can be wrongly false For some reasons, sometime `item.inherited` is `false` even if the item was added to the `all_module_kinds` table by the "hierarchy lookup" for-loop, and we already force the `inherited` property to be sets to `true` at this moment. With this commit, we add a second fail-check condition based on the `item.baseclass` property to determine if the item is inherited or not when we do the render.
2021-03-27 15:42:20 +01:00
&middot;&nbsp;Inherited from $(M(item.baseclass, item))
Implement inheritance into ldoc template. This use the new `@baseclass` and `@inherited` tags to add inheritance data to the rendered documentation.
2019-11-26 13:46:44 +01:00
# end
doc: Add a summary next to the property/method title.
2019-11-28 09:04:26 +01:00
# if item.extra_summary then
# for _, col in ldoc.ipairs(item.extra_summary) do
doc: Make use of the @classsignal tag. It wasn't doing anything until now.
2019-12-31 07:45:43 +01:00
&middot $((col.showcount and col.count.." " or "")..col.title)
doc: Add a summary next to the property/method title.
2019-11-28 09:04:26 +01:00
# end -- summary col
# end -- summary
</span>
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# if ldoc.prettify_files and ldoc.is_file_prettified[item.module.file.filename] then
<a style="float:right;" href="$(ldoc.source_ref(item))">line $(item.lineno)</a>
# end
</dt>
<dd>
$(M(ldoc.descript(item),item))
doc: Add support for property types to ldoc. Rather that abusing of how the arguments are displayed to convey the type, add native support. It still uses the @param for the doc, so this doesn't cause a million little noisy changes, but the rendered HTML now have a real section for the type. This is added to both the summary and the expanded description. Additionally, if the type has a description string, a second is added.
2019-06-08 04:53:36 +02:00
# if show_parms and item.params and #item.params > 0 and not item.hide_params then
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# local subnames = module.kinds:type_of(item).subnames
# if subnames then
<h3>$(subnames):</h3>
# end
doc: Replace the function argument rendering. This is an attempt at solving several problems reported by novice users. The old rendering was very compact and quite fine once you got used to its, ..., "conventions". But it was also sometime rather hard to read. First of all, it abused bold and italic. It also "merged" optional parameters and parameters with default content. It got worst when the documentation was spread over mutiple lines. For property types and constructors with large number of parameters, it was also quite unreadable. The new representation, while far from perfect, is less dense and more explicit. It has a separate column for "optional" using the new "metadata chip" documentation concept. It is also an aligned table and correctly renders multi-line documentation. Finally, it adds a "note" message when the named parameter convention is used. This way the users looking at the examples will be less confused.
2021-12-17 22:34:49 +01:00
# local has_optional, has_named_call = false, false
# for parm in iter(item.params) do
# local param,sublist = item:subparam(parm)
# has_named_call = has_named_call or (sublist and item.is_named_call)
# for p in iter(param) do
# local def = item:default_of_param(p)
# has_optional = has_optional or (def and def ~= true)
# end
# end
# if has_named_call then
<div class="important_box">
<b>Note:</b> This $(item.kind) uses named parameters calling convention. It
means you call it with $(M('`{}`')) and omit the parantheses. For example,
calling this will all default argument would be <code>$(item.name){}</code>.
This is a Lua shortcut syntax equivalent to <code>$(item.name)({})</code>.
<code>args</code> is only a placeholder name for the "lone table argument"
used in named parameters calls.
</div>
# end
<table class="see_also">
<tr class="param_header">
<th>Name</th>
<th></th>
<th>Type(s)</th>
<th>Description</th>
# if has_optional then
<th>Default value</th>
# end
</tr>
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# for parm in iter(item.params) do
# local param,sublist = item:subparam(parm)
# if sublist then
doc: Replace the function argument rendering. This is an attempt at solving several problems reported by novice users. The old rendering was very compact and quite fine once you got used to its, ..., "conventions". But it was also sometime rather hard to read. First of all, it abused bold and italic. It also "merged" optional parameters and parameters with default content. It got worst when the documentation was spread over mutiple lines. For property types and constructors with large number of parameters, it was also quite unreadable. The new representation, while far from perfect, is less dense and more explicit. It has a separate column for "optional" using the new "metadata chip" documentation concept. It is also an aligned table and correctly renders multi-line documentation. Finally, it adds a "note" message when the named parameter convention is used. This way the users looking at the examples will be less confused.
2021-12-17 22:34:49 +01:00
# local def = item:default_of_param(sublist)
<tr>
<td><span class="parameter">$(sublist)</span></td>
<td>$(def and '<span class="chips">Optional</span>' or '')</td>
<td><span class="types"><span class="type">table</span></span></td>
<td class="see_also_description">$(M(item.params.map[sublist],item)) </td>
# if has_optional then
# if def and def ~= true then
<td><span class="default_value"><code>$(def)</code></span></td>
# elseif def then
<td><span class="not_applicable">Undefined</span></td>
# else
<td><span class="not_applicable" title="This parameter is mandatory">Not applicable</span></td>
# end
# end
</tr>
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# 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)
doc: Replace the function argument rendering. This is an attempt at solving several problems reported by novice users. The old rendering was very compact and quite fine once you got used to its, ..., "conventions". But it was also sometime rather hard to read. First of all, it abused bold and italic. It also "merged" optional parameters and parameters with default content. It got worst when the documentation was spread over mutiple lines. For property types and constructors with large number of parameters, it was also quite unreadable. The new representation, while far from perfect, is less dense and more explicit. It has a separate column for "optional" using the new "metadata chip" documentation concept. It is also an aligned table and correctly renders multi-line documentation. Finally, it adds a "note" message when the named parameter convention is used. This way the users looking at the examples will be less confused.
2021-12-17 22:34:49 +01:00
<tr$(sublist and ' class="see_also_sublist"' or '')>
<td><span class="parameter">$(name)</span></td>
<td>$(def and '<span class="chips">Optional</span>' or '')</td>
<td><span class="types">$(tp)</span></td>
<td class="see_also_description">$(M(item.params.map[p],item))</td>
# if has_optional then
# if def and def ~= true then
<td><span class="default_value"><code>$(def)</code></span></td>
# elseif def then
<td><span class="not_applicable">Undefined</span></td>
# else
<td><span class="not_applicable" title="This parameter is mandatory">Not applicable</span></td>
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# end
doc: Replace the function argument rendering. This is an attempt at solving several problems reported by novice users. The old rendering was very compact and quite fine once you got used to its, ..., "conventions". But it was also sometime rather hard to read. First of all, it abused bold and italic. It also "merged" optional parameters and parameters with default content. It got worst when the documentation was spread over mutiple lines. For property types and constructors with large number of parameters, it was also quite unreadable. The new representation, while far from perfect, is less dense and more explicit. It has a separate column for "optional" using the new "metadata chip" documentation concept. It is also an aligned table and correctly renders multi-line documentation. Finally, it adds a "note" message when the named parameter convention is used. This way the users looking at the examples will be less confused.
2021-12-17 22:34:49 +01:00
# end
</tr>
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# end
# end -- for
doc: Replace the function argument rendering. This is an attempt at solving several problems reported by novice users. The old rendering was very compact and quite fine once you got used to its, ..., "conventions". But it was also sometime rather hard to read. First of all, it abused bold and italic. It also "merged" optional parameters and parameters with default content. It got worst when the documentation was spread over mutiple lines. For property types and constructors with large number of parameters, it was also quite unreadable. The new representation, while far from perfect, is less dense and more explicit. It has a separate column for "optional" using the new "metadata chip" documentation concept. It is also an aligned table and correctly renders multi-line documentation. Finally, it adds a "note" message when the named parameter convention is used. This way the users looking at the examples will be less confused.
2021-12-17 22:34:49 +01:00
</table>
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# end -- if params
# if show_return and item.retgroups then local groups = item.retgroups
<h3>Returns:</h3>
# for i,group in ldoc.ipairs(groups) do local li,il = use_li(group)
<ol>
# for r in group:iter() do local type, ctypes = item:return_type(r); local rt = ldoc.typename(type)
$(li)
# if rt ~= '' then
<span class="types">$(rt)</span>
# end
$(M(r.text,item))$(il)
# if ctypes then
<ul>
# for c in ctypes:iter() do
<li><span class="parameter">$(c.name)</span>
<span class="types">$(ldoc.typename(c.type))</span>
$(M(c.comment,item))</li>
# end
</ul>
# end -- if ctypes
# end -- for r
</ol>
# if i < #groups then
<h3>Or</h3>
# end
# end -- for group
# end -- if returns
# if show_return and item.raise then
<h3>Raises:</h3>
$(M(item.raise,item))
# end
# if item.see then
# local li,il = use_li(item.see)
<h3>See also:</h3>
doc: Improve the "See also" section. Now display: * The description summary. * The item kind. * The module name (if non-local).
2021-12-14 21:14:32 +01:00
<table class="see_also">
# for see in iter(item.see) do
# local see_item = see.mod and get_item(see.mod, see.name)
# local see_mod = (see_item and see.mod and see.mod ~= item.module and see.mod.name ~= see_item.name) and "("..see.mod.name..")" or ""
<tr>
<td><a href="$(ldoc.href(see))" title="In the $(see.mod and see.mod.name) module.">$(see.label)</a></td>
<td>$(see_item and M(see_item.summary)) $(see_mod)</td>
<td>
# if see_item or see.name == "" then
<span class="chips">$(see.name == "" and "module" or (see_item and see_item.kind))</span>
# end
</td>
<tr>
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# end -- for
doc: Improve the "See also" section. Now display: * The description summary. * The item kind. * The module name (if non-local).
2021-12-14 21:14:32 +01:00
</table>
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# end -- if see
# if item.usage then
# local li,il = use_li(item.usage)
<h3>Usage:</h3>
<ul>
# for usage in iter(item.usage) do
doc: Fix the rendering of double quotes and semicolons CMake uses quotes and semicolon in its internal list datatype. Previously, all double quotes were converted to single quotes to avoid this problem. Semicolors were interpreted as newlines in ldoc. With this commit, both of them render fine. This was required because a new example uses CSS and XML where those symbols have a specific meanning.
2021-09-12 03:59:46 +02:00
$(li)<pre class="example">$(ldoc.prettify(un_cmake(usage)))</pre>$(il)
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# end -- for
</ul>
# end -- if usage
doc: Make use of the @classsignal tag. It wasn't doing anything until now.
2019-12-31 07:45:43 +01:00
# if item.has_show_more then
doc: Add a summary next to the property/method title.
2019-11-28 09:04:26 +01:00
<br />
<center id=button$(item.uid)>
<a class="show_more_button" onclick="show_extra('$(item.uid)')">
Click to display more
</a>
</center>
# end
doc: Hide the newly auto-generated content by default. First of all, yes, JavaScript in the doc. I don't like this either. The reason is that the new sections are super useful *when you need them*. However, in practice, that's rare. So better not make the signal to noise ratio worst. Future commit will introduce an auto-generated summary of what's hidden.
2019-11-25 05:59:27 +01:00
<span id=item$(item.uid) class="hide_extra">
# 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 group_begin, group_end, row_type_begin, row_type_end, group_header = item.get_delim(custom[1])
<h3>$(custom.title or custom[1]):</h3>
<$(group_begin)>
# if group_header then
<tr style='font-weight: bold;'>
# for _, g in ldoc.ipairs(group_header) do
<th>$(g)</th>
# end -- for g
</tr>
# end -- if group_header then
# for value in iter(tag) do
<$(row_type_begin)>$(custom.format and custom.format(value, item, M) or M(value))</$(row_type_end)>
# local sub_values, sub_custom = item.get_auto_params(custom[1], value)
# if sub_values then
<ul>
# for _, value in ldoc.ipairs(sub_values) do
<li>$(sub_custom.format(value, item, M))</li>
# end -- for auto_params
</ul>
# end -- if item.auto_params
# end -- for
</$(group_end)>
# end -- if tag
# end -- iter tags
# end -- ldoc.custom_tags
</span>
doc: Update the template to render sub-tags. Sub-tags are a new concept and is equivalent to @tparam, but in a generic form.
2019-11-24 09:59:38 +01:00
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
</dd>
doc(@hidden;ldoc.ltp): Add ldoc tag to hide item Add a new ldoc tag `@hidden`. This tag allows us to keep documentation for magic methods (e.g. `wibox.widget.base:get_visible`) but prevent it from being part of the documentation used by final users.
2021-03-28 18:19:08 +02:00
# end end -- for items
doc: Modify the template to allow merging sections. It might not be the most pretty of change, but it works. With this change, it is possible to have multiple "things" in the "same" section having the "same" name. This allows for C/C++ style functions with the same name but different signatures. Lua doesn't handle this well, so it should usually be avoided. However, constructors might be a valid exception. Most older widget (and object) constructors have multiple random argument while newer one use `args`. Deprecating the old ones for the sake of standardization might be a bit too much for users upgrading from v3.5. Given the only reason all of those deprecation would happen is because "its pretty that way", then lets allow 2 constructors and avoid outrage.
2019-10-27 20:39:23 +01:00
# last_kind = kind
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# end -- for kinds
doc: Modify the template to allow merging sections. It might not be the most pretty of change, but it works. With this change, it is possible to have multiple "things" in the "same" section having the "same" name. This allows for C/C++ style functions with the same name but different signatures. Lua doesn't handle this well, so it should usually be avoided. However, constructors might be a valid exception. Most older widget (and object) constructors have multiple random argument while newer one use `args`. Deprecating the old ones for the sake of standardization might be a bit too much for users upgrading from v3.5. Given the only reason all of those deprecation would happen is because "its pretty that way", then lets allow 2 constructors and avoid outrage.
2019-10-27 20:39:23 +01:00
</dl>
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# else -- if module; project-level contents
# if ldoc.description then
<h2>$(M(ldoc.description,nil))</h2>
# end
# if ldoc.full_description then
<p>$(M(ldoc.full_description,nil))</p>
# end
# for kind, mods in ldoc.kinds() do
<h2>$(kind)</h2>
# kind = kind:lower()
<table class="module_list">
# for m in mods() do
doc: Do not mix spaces and tabs for indentation in the generated HTML.
2019-07-09 23:00:20 +02:00
<tr>
<td class="name" $(nowrap)><a href="$(html_space(kind))/$(m.name).html">$(m.name)</a></td>
<td class="summary">$(M(ldoc.strip_header(m.summary),m))</td>
</tr>
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
# end -- for modules
</table>
# end -- for kinds
# end -- if module
</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc $(ldoc.version)</a></i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
doc: Implement responsive, toggleable sidebar Below a screen width of 768px (Bootstrap's "medium" breakpoint) the sidebar will collapse to a small strip. Hovering the sidebar will fully reveal it until the mouse leaves it. Clicking the sidebar will reveal it until another part of the page is clicked.
2021-12-14 16:32:47 +01:00
<script defer type="text/javascript">
const $nav = document.querySelector("#navigation");
// When clicking the sidebar, open it
$nav.addEventListener("click", function(ev) {
if (document.body.clientWidth >= 768) {
return;
}
const target = $nav;
if (!target.classList.contains("open")) {
target.classList.add("open");
ev.stopPropagation();
}
});
// When clicking anywhere else than the sidebar, close it
document.querySelector("body").addEventListener("click", function(ev) {
if (document.body.clientWidth >= 768 || ev.target.contains($nav)) {
return;
}
const target = $nav;
if (target.classList.contains("open")) {
target.classList.remove("open");
}
});
add(ltp) .function anchor copy link to clipboard
2022-01-02 17:12:38 +01:00
const copyResultClasses = {
success : "copy-link--success",
failure: "copy-link--failure"
};
const removeCopyResultClasses = ($target) =>
Object.values(copyResultClasses).forEach(c => $target.classList.remove(c));
document.querySelectorAll(".js-copy-link").forEach(copyLink => {
copyLink.addEventListener("click", function(e) {
e.preventDefault();
const $target = e.target;
removeCopyResultClasses($target);
let link = $target.href;
if (!link) {
return;
}
if (link.startsWith("#")) {
const curr = window.location.pathname;
link = curr.substring(0, curr.indexOf("#")) + link;
}
// We need to create a fake element to copy the text from
const fakeElement = document.createElement("textarea");
fakeElement.value = link;
document.body.appendChild(fakeElement);
fakeElement.select();
let success = false;
try {
success = document.execCommand("copy");
} catch(err) {
success = false;
}
fakeElement.remove();
$target.classList.add(success ? copyResultClasses.success : copyResultClasses.failure);
setInterval(() => removeCopyResultClasses($target), 1500);
});
});
doc: Implement responsive, toggleable sidebar Below a screen width of 768px (Bootstrap's "medium" breakpoint) the sidebar will collapse to a small strip. Hovering the sidebar will fully reveal it until the mouse leaves it. Clicking the sidebar will reveal it until another part of the page is clicked.
2021-12-14 16:32:47 +01:00
</script>
ldoc: prepare for custom ldoc.ltp ldoc.ltp is copied from ldoc (ldoc/html/ldoc_ltp.lua).
2019-01-04 14:19:21 +01:00
</body>
</html>