{"id":14128185,"url":"https://github.com/lunarmodules/LDoc","last_synced_at":"2025-08-03T22:32:29.522Z","repository":{"id":37094471,"uuid":"1605012","full_name":"lunarmodules/ldoc","owner":"lunarmodules","description":"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.","archived":false,"fork":false,"pushed_at":"2024-07-22T09:36:22.000Z","size":1018,"stargazers_count":794,"open_issues_count":102,"forks_count":173,"subscribers_count":33,"default_branch":"master","last_synced_at":"2024-12-05T15:05:19.682Z","etag":null,"topics":["code-documentation","documentation","documentation-tool","ldoc","lua","luadoc","penlight"],"latest_commit_sha":null,"homepage":"https://lunarmodules.github.io/ldoc/","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lunarmodules.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-04-12T16:44:35.000Z","updated_at":"2024-12-01T23:51:11.000Z","dependencies_parsed_at":"2024-01-03T01:19:32.812Z","dependency_job_id":"5296788f-0279-4529-8d45-e2138be9c7b9","html_url":"https://github.com/lunarmodules/ldoc","commit_stats":{"total_commits":539,"total_committers":63,"mean_commits":8.555555555555555,"dds":"0.33580705009276435","last_synced_commit":"f91ed4b76bec011a2e76cfe1283877686af8377e"},"previous_names":["stevedonovan/ldoc"],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lunarmodules%2Fldoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lunarmodules%2Fldoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lunarmodules%2Fldoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lunarmodules%2Fldoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lunarmodules","download_url":"https://codeload.github.com/lunarmodules/ldoc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228571844,"owners_count":17938772,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-documentation","documentation","documentation-tool","ldoc","lua","luadoc","penlight"],"created_at":"2024-08-15T16:01:23.135Z","updated_at":"2024-12-07T06:30:57.216Z","avatar_url":"https://github.com/lunarmodules.png","language":"Lua","readme":"# LDoc - A Lua Documentation Tool\n\n[![Luacheck](https://github.com/lunarmodules/ldoc/workflows/Luacheck/badge.svg)](https://github.com/lunarmodules/ldoc/actions)\n\nCopyright (C) 2011-2012 Steve Donovan.\n\n## Rationale\n\nThis project grew out of the documentation needs of\n[Penlight](https://github.com/lunarmodules/Penlight) (and not always getting satisfaction\nwith LuaDoc) and depends on Penlight itself. (This allowed me to _not_ write a lot of code.)\n\nThe [API documentation](https://lunarmodules.github.io/Penlight/) of Penlight\nis an example of a project using plain LuaDoc markup processed using LDoc.\n\nLDoc is intended to be compatible with [LuaDoc](https://keplerproject.github.io/luadoc/) and\nthus follows the pattern set by the various \\*Doc tools:\n\n    --- Summary ends with a period.\n    -- Some description, can be over several lines.\n    -- @param p1 first parameter\n    -- @param p2 second parameter\n    -- @return a string value\n    -- @see second_fun\n    function mod1.first_fun(p1,p2)\n    end\n\nTags such as `see` and `usage` are supported, and generally the names of functions and\nmodules can be inferred from the code.\n\nLDoc is designed to give better diagnostics: if a `@see` reference cannot be found, then the\nline number of the reference is given.  LDoc knows about modules which do not use `module()`\n- this is important since this function has become deprecated in Lua 5.2. And you can avoid\nhaving to embed HTML in comments by using Markdown.\n\nLDoc will also work with Lua C extension code, and provides some convenient shortcuts.\n\nAn example showing the support for named sections and 'classes' is the [Winapi\ndocumentation](https://stevedonovan.github.io/winapi/api.html); this is generated from\n[winapi.l.c](https://github.com/stevedonovan/winapi/blob/master/winapi.l.c).\n\n## Installation\n\nThis is straightforward; the only external dependency is\n[Penlight](https://github.com/lunarmodules/Penlight), which in turn needs\n[LuaFileSystem](https://lunarmodules.github.io/luafilesystem/). These are already present\nin [Lua for Windows](https://github.com/rjpcomputing/luaforwindows), and Penlight is also available through [LuaRocks](https://luarocks.org/) as `luarocks install\npenlight`.\n\nUnpack the sources somewhere and make an alias to `ldoc.lua` on your path. That is, either\nan executable script called 'ldoc' like so:\n\n    lua /path/to/ldoc/ldoc.lua $*\n\nOr a batch file called 'ldoc.bat':\n\n    @echo off\n    lua \\path\\to\\ldoc\\ldoc.lua %*\n\n\n## Generating LDoc on github\n\nTo generate docs for your own lua projects see [doc.yml](.github/workflows/doc.yml).\n\nInstead of `luarocks install --only-deps ...`, use `luarocks install ldoc`\nand create your own `doc-site` makefile target that runs `ldoc .` in the\ndirectory containing your `config.ld`.\n\nEnsure `publish_dir` in your doc.yml is set to the same location as your\n`config.ld`'s `dir` parameter.\n\nAfter you've pushed that change to master, you'll see the build cycle on your\ncommit (an orange dot or green checkmark). When that completes, a repo owner\nneeds to enable gh-pages on the repository: Settings \u003e Pages and set \"Source\" to\ngh-pages and root.\n\n## Docker\n\nAlternatively LDoc can be run as a standalone docker container.\nThe usage of docker is fairly simple.\nYou can either build your own or download a prebuilt version.\nTo build your own, execute the following command from the source directory of this project:\n\n```console\n$ docker build -t ghcr.io/lunarmodules/ldoc:HEAD .\n```\n\nTo use a prebuilt one, download it from the GitHub Container Registry.\nHere we use the one tagged *latest*, but you can substitute *latest* for any tagged release.\n\n```console\n$ docker pull ghcr.io/lunarmodules/ldoc:latest\n```\n\nOnce 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):\n\n```console\n# Run in the current directory\n$ docker run -v \"$(pwd):/data\" ghcr.io/lunarmodules/ldoc:latest .\n```\n\nA less verbose way to run it in most shells is with at alias:\n\n```console\n# In a shell or in your shell's RC file:\n$ alias ldoc='docker run -v \"$(pwd):/data\" ghcr.io/lunarmodules/ldoc:latest'\n\n# Thereafter just run:\n$ ldoc .\n```\n### Use as a CI job\n\nThere are actually many ways to run LDoc remotely as part of a CI work flow.\nBecause 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.\nAnother way is to pull in the prebuilt Docker container and run that.\n\nAs a case study, here is how a workflow could be setup in GitHub Actions:\n\n```yaml\nname: LDoc\non: [ push, pull_request ]\njobs:\n  sile:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v3\n      - name: Generate docs with LDoc\n        uses: lunarmodules/ldoc@v0\n```\n\nBy default the GH Action is configured to run `ldoc .`, but you can also pass it your own `args` to replace the default input of `.`.\n\n```yaml\n      - name: Generate docs with LDoc\n        uses: lunarmodules/ldoc@v0\n        with:\n            args: myfile.lua\n```\n","funding_links":[],"categories":["Lua"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flunarmodules%2FLDoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flunarmodules%2FLDoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flunarmodules%2FLDoc/lists"}