• Stars
    star
    755
  • Rank 58,636 (Top 2 %)
  • Language
    Lua
  • License
    Other
  • Created about 13 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

LDoc is a LuaDoc-compatible documentation generator which can also process C extension source. Markdown may be optionally used to render comments, as well as integrated readme documentation and pretty-printed example files.

LDoc - A Lua Documentation Tool

Luacheck

Copyright (C) 2011-2012 Steve Donovan.

Rationale

This project grew out of the documentation needs of Penlight (and not always getting satisfaction with LuaDoc) and depends on Penlight itself. (This allowed me to not write a lot of code.)

The API documentation of Penlight is an example of a project using plain LuaDoc markup processed using LDoc.

LDoc is intended to be compatible with LuaDoc and thus follows the pattern set by the various *Doc tools:

--- Summary ends with a period.
-- Some description, can be over several lines.
-- @param p1 first parameter
-- @param p2 second parameter
-- @return a string value
-- @see second_fun
function mod1.first_fun(p1,p2)
end

Tags such as see and usage are supported, and generally the names of functions and modules can be inferred from the code.

LDoc is designed to give better diagnostics: if a @see reference cannot be found, then the line number of the reference is given. LDoc knows about modules which do not use module()

  • this is important since this function has become deprecated in Lua 5.2. And you can avoid having to embed HTML in comments by using Markdown.

LDoc will also work with Lua C extension code, and provides some convenient shortcuts.

An example showing the support for named sections and 'classes' is the Winapi documentation; this is generated from winapi.l.c.

Installation

This is straightforward; the only external dependency is Penlight, which in turn needs LuaFileSystem. These are already present in Lua for Windows, and Penlight is also available through LuaRocks as luarocks install penlight.

Unpack the sources somewhere and make an alias to ldoc.lua on your path. That is, either an executable script called 'ldoc' like so:

lua /path/to/ldoc/ldoc.lua $*

Or a batch file called 'ldoc.bat':

@echo off
lua \path\to\ldoc\ldoc.lua %*

Generating LDoc on github

To generate docs for your own lua projects see doc.yml.

Instead of luarocks install --only-deps ..., use luarocks install ldoc and create your own doc-site makefile target that runs ldoc . in the directory containing your config.ld.

Ensure publish_dir in your doc.yml is set to the same location as your config.ld's dir parameter.

After you've pushed that change to master, you'll see the build cycle on your commit (an orange dot or green checkmark). When that completes, a repo owner needs to enable gh-pages on the repository: Settings > Pages and set "Source" to gh-pages and root.

Docker

Alternatively LDoc can be run as a standalone docker container. The usage of docker is fairly simple. You can either build your own or download a prebuilt version. To build your own, execute the following command from the source directory of this project:

$ docker build -t ghcr.io/lunarmodules/ldoc:HEAD .

To use a prebuilt one, download it from the GitHub Container Registry. Here we use the one tagged latest, but you can substitute latest for any tagged release.

$ docker pull ghcr.io/lunarmodules/ldoc:latest

Once you have a container you can run it on one file or a source tree (substitute latest with HEAD if you built your own or with the tagged version you want if applicable):

# Run in the current directory
$ docker run -v "$(pwd):/data" ghcr.io/lunarmodules/ldoc:latest .

A less verbose way to run it in most shells is with at alias:

# In a shell or in your shell's RC file:
$ alias ldoc='docker run -v "$(pwd):/data" ghcr.io/lunarmodules/ldoc:latest'

# Thereafter just run:
$ ldoc .

Use as a CI job

There are actually many ways to run LDoc remotely as part of a CI work flow. Because packages are available for many platforms, one way would be to just use your platforms native package installation system to pull them into whatever CI runner environment you already use. Another way is to pull in the prebuilt Docker container and run that.

As a case study, here is how a workflow could be setup in GitHub Actions:

name: LDoc
on: [ push, pull_request ]
jobs:
  sile:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Generate docs with LDoc
        uses: lunarmodules/ldoc@v0

By default the GH Action is configured to run ldoc ., but you can also pass it your own args to replace the default input of ..

      - name: Generate docs with LDoc
        uses: lunarmodules/ldoc@v0
        with:
            args: myfile.lua

More Repositories

1

Penlight

A set of pure Lua libraries focusing on input data handling (such as reading configuration files), functional programming (such as map, reduce, placeholder expressions,etc), and OS path management. Much of the functionality is inspired by the Python standard libraries.
Lua
1,838
star
2

luasocket

Network support for the Lua language
HTML
1,774
star
3

busted

Elegant Lua unit testing.
Lua
1,347
star
4

luafilesystem

LuaFileSystem is a Lua library developed to complement the set of functions related to file systems offered by the standard Lua distribution.
C
876
star
5

luasql

LuaSQL is a simple interface from Lua to a DBMS.
Lua
528
star
6

luasec

LuaSec
C
357
star
7

luacov

LuaCov is a simple coverage analyzer for Lua code.
Lua
293
star
8

lua-compat-5.3

Compatibility module providing Lua-5.3-style APIs for Lua 5.2 and 5.1
C
222
star
9

luassert

Assertion library for Lua
Lua
198
star
10

copas

Copas is a dispatcher based on coroutines that can be used by TCP/IP servers.
Lua
198
star
11

lua_cliargs

A command-line argument parsing module for Lua.
Lua
114
star
12

md5

MD5 offers basic cryptographic facilities for Lua 5.1.
C
107
star
13

cgilua

CGILua is a tool for creating dynamic HTML pages and manipulating input data from Web forms.
Lua
92
star
14

lua-iconv

Lua bindings for POSIX iconv
Lua
89
star
15

lualogging

A simple API to use logging features in Lua
Lua
48
star
16

say

Lua string hashing library, useful for internationalization
Lua
41
star
17

luaexpat

LuaExpat is a SAX XML parser based on the Expat library
Lua
20
star
18

luasystem

Platform independent system calls for Lua
Lua
17
star
19

luasyslog

Addon for lualogging to log to the system log on unix systems
Lua
5
star
20

lua-mimetypes

fixed repo of https://luarocks.org/modules/luarocks/mimetypes
Lua
4
star
21

lunarmodules

providing the profile page (README.md) for the Lunar Modules organization
2
star
22

moon-sand

Sandbox to mess with CIโ€Œ deployments using LunarModules CI key(s)
Lua
1
star
23

expadom

An XML DOM Level 2 Core implementation in Lua, based on the (Lua)Expat parser.
Lua
1
star
24

.github

Lunarmodules profile page and reusable workflows
1
star
25

lua-lace

Lua Access Control Engine
Lua
1
star