Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve markdown template #346

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
272 changes: 260 additions & 12 deletions ldoc/html/ldoc_md_ltp.lua
Original file line number Diff line number Diff line change
@@ -1,17 +1,265 @@
return [[
> local lev = ldoc.level or 2
> local lev1,lev2 = ('#'):rep(lev),('#'):rep(lev+1)
> for kind, items in module.kinds() do
> local kitem = module.kinds:get_item(kind)
> if kitem then
$(lev1) $(ldoc.descript(kitem))
!local no_spaces = ldoc.no_spaces
!local function use_li(ls) return #ls > 1 and '- ' or '' end
!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'

> end
> for item in items() do
$(lev2) $(ldoc.display_name(item))
!-- Menu --

$(ldoc.descript(item))
# $(ldoc.project)

> end
> end
!if not ldoc.single and module then -- reference back to project index
[Index]($(ldoc.output))
!end

!--------- contents of module -------------
!if module and not ldoc.no_summary and #module.items > 0 then
## Contents

! for kind,items in module.kinds() do
- [$(kind)](#$(no_spaces(kind)))
! end
!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

## $(kind)

! for item in items() do
- [$(display_name(item))](#$(item.name))
! end
! end
!end

!-------- 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

## $(kind)

! for mod in mods() do local name = display_name(mod)
! if mod.name == this_mod then
- **$(name)**
! else
- [$(name)]($(ldoc.ref_to_module(mod):gsub('.html', '')))
! end
! end
! end
!end

---

!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 = use_li(module.see)
### See also:

! for see in iter(module.see) do
$(li)[$(see.label)]($(ldoc.href(see):gsub('.html', '')))
! end -- for
! end -- if see

! if module.usage then
! local li = use_li(module.usage)
### Usage:

! for usage in iter(module.usage) do
$(li)```lua
$(ldoc.escape(usage))
```
! 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)](#$(no_spaces(kind)))

|||
|-|-|
! for item in items() do
[$(display_name(item))](#$(item.name))|$(M(item.summary,item))
! end -- for items
! 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:

```lua
$(ldoc.prettify(kitem.usage[1]))
```
! end
! end

! for item in items() do
! if ldoc.prettify_files and ldoc.is_file_prettified[item.module.file.filename] then
### **$(display_name(item))**<span style='float:right;'>[line $(item.lineno)]($(ldoc.source_ref(item):gsub('.html', '')))</span>
! else
### **$(display_name(item))**
! 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 = use_li(tag)
#### $(custom.title or custom[1]):

! for value in iter(tag) do
$(li)$(custom.format and custom.format(value) or M(value))
! 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)
! local indent = sublist and ' ' or ''
! 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)
$(indent)- `$(name)`:
! if tp ~= '' then
($(tp))
! end
! if def == true then
(_optional_)
! elseif def then
(_default_: $(def))
! end
! if item:readonly(p) then
(_readonly_)
! end
$(M(item.params.map[p],item))
! 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 oli,uli = #group > 1 and '1. ',' - ' or '','- '
! for r in group:iter() do
! local type, ctypes = item:return_type(r)
! local rt = ldoc.typename(type)
$(oli)$(rt ~= '' and '('..rt..')' or '') $(M(r.text,item))
! if ctypes then
! for c in ctypes:iter() do
$(uli)`$(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 = use_li(item.see)
#### See also:

! for see in iter(item.see) do
$(li)[$(see.label)]($(ldoc.href(see):gsub('.html', '')))
! end -- for
! end -- if see

! if item.usage then
! local li = use_li(item.usage)
#### Usage:

! for usage in iter(item.usage) do
$(li)```lua
$(ldoc.prettify(usage))
```
! 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
[$(m.name)]($(no_spaces(kind))/$(m.name))|$(M(ldoc.strip_header(m.summary),m))
! end -- for modules

! end -- for kinds
!end -- if module

---

<i>generated by [LDoc $(ldoc.version)](http://github.com/stevedonovan/LDoc)</i>
<i style='float:right;'>Last updated $(ldoc.updatetime)</i>
]]