{"id":19396910,"url":"https://github.com/jtackaberry/luadox","last_synced_at":"2025-04-24T05:30:58.053Z","repository":{"id":144720679,"uuid":"376651061","full_name":"jtackaberry/luadox","owner":"jtackaberry","description":"Lua API documentation generator","archived":false,"fork":false,"pushed_at":"2025-03-02T23:27:23.000Z","size":362,"stargazers_count":18,"open_issues_count":14,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-02T23:13:07.021Z","etag":null,"topics":["documentation","generator","lua"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jtackaberry.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2021-06-13T22:22:02.000Z","updated_at":"2025-03-02T23:27:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"c1814c8a-ff69-4edc-9904-a8937f9b0f2d","html_url":"https://github.com/jtackaberry/luadox","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtackaberry%2Fluadox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtackaberry%2Fluadox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtackaberry%2Fluadox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtackaberry%2Fluadox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jtackaberry","download_url":"https://codeload.github.com/jtackaberry/luadox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250572195,"owners_count":21452326,"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":["documentation","generator","lua"],"created_at":"2024-11-10T10:38:38.591Z","updated_at":"2025-04-24T05:30:58.038Z","avatar_url":"https://github.com/jtackaberry.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LuaDox - Lua Documentation Generator\n\n**👉 [Download the latest release](https://github.com/jtackaberry/luadox/releases/latest)**\n\n📘 You can find an example of LuaDox's output **[here](https://reapertoolkit.dev)**\n\nLuaDox is:\n * born out of personal frustration with LDoc which repeatedly failed to work how I expected/wanted\n   (which is perhaps more an indictment of me than of LDoc, as LuaDox is probably also accidentally\n   opinionated about structure)\n * an attempt to make nice looking and searchable documentation generated from code\n * written in Python, strangely enough.  Python 3.8 or later is required.\n * *not* strictly compatible with LuaDoc or LDoc tags and not a drop-in replacement, although obviously\n   heavily influenced by them\n\nMarkdown is used for styling, both in comments as well as standalone manual files,\nand `inline code` is implicitly resolved to linkable references (if such a reference\nexists).  Standard markdown is supported, plus tables.\n\nA brief example using [middleclass](https://github.com/kikito/middleclass):\n\n```lua\n--- Utility class to manipulate files.\n--\n-- @class xyz.File\n-- @inherits xyz.Base\nxyz.File = class('xyz.File', xyz.Base)\n\n--- Seek constants.\n--\n-- These constants can be used with `seek()`.\n--\n-- @section seekconst\n-- @compact\n\n--- Seek from the beginning of the file.\nxyz.File.static.SEEK_SET = 'set'\n--- Seek from the current position.\nxyz.File.static.SEEK_CUR = 'cur'\n--- Seek to the end of the file.\nxyz.File.static.SEEK_END = 'end'\n\n--- Class API.\n--- @section api\n\n--- Opens a new file.\n--\n-- @example\n--   f = xyz.File('/etc/passwd')\n--   f.seek(xyz.File.SEEK_END)\n--\n-- @tparam string name the path to the file to open\n-- @tparam string|nil mode the access mode, where `r` is read-only and `w` is read-write.\n--   Nil assumes `r`.\n-- @treturn xyz.File a new file object\n-- @display xyz.File\nfunction xyz.File:initialize(name, mode)\n    -- ...\nend\n\n--- Seeks within the file.\n--\n-- @tparam seekconst|nil whence position to seek from, or nil to get current position\n-- @tparam number|nil offset the number of bytes relative to `whence` to seek\n-- @treturn number byte position within the file\nfunction xyz.File:seek(whence, offset)\n  -- ...\nend\n```\n\nAnd the simplest possible usage:\n\n```bash\n# Linux and OS X\nluadox file.lua\n\n# Windows\npython luadox file.lua\n```\n\nWhich assumes a bunch of defaults, one of which is that the output directory `out/` is\ncreated with the rendered documentation.  Obviously this and other customizations can\nbe configured either by command line arguments and/or config file (see later).\n\n\n## The Basics\n\n### Documenting Elements\n\nLuaDox ignores standard Lua comments until a block of comments begins with three dashes,\nwhich is the marker that begins a **documentation block**:\n\n```lua\n--- This begins a LuaDox documentation block.\n--\n-- After this point, we can use double dashes.  Anything that follows is\n-- considered part of the documentation up until the next non-comment\n-- line, which also includes blank lines, whereupon the block terminates.\n--\n-- Here we declare this comment to be the preamble to a module page.\n--\n-- @module mymod\n```\n\nThe above example creates a new *element* (specifically a module element), which\nmeans it is a block of documentation that can be explicitly *referenced*.  In this\ncase, the reference name is `mymod`, which means elsewhere in documentation (whether\nin the same file or another file), this can be linked using one of 3 methods as\nshown below:\n\n```lua\n--- Here begins another block of documentation.\n--\n-- This one documents a function, because a function definition immediately follows\n-- the comment block.\n--\n-- Also, we can link to @{mymod} like this, which converts to a hyperlink.  Or you\n-- can control the link text @{mymod|so this text links to mymod}.  It's also possible\n-- to use inline code markdown like this: `mymod`.\nfunction example()\nend\n```\n\n### Collections\n\n`@module` (along with `@class`, `@section`, and `@table`) are special types of elements\ncalled *collections*.  Functions and fields that have LuaDox comment marker (i.e. `---`)\npreceding their definitions belong to the most recently defined collection element (at\nleast unless the `@within` tag is used to relocate it somewhere else). Collections show\na summary table of all functions and methods, and then itemize each of them below the\nsummary table in more detail. In the above example, the `example()` function would belong\ndirectly to the `mymod` collection.\n\nBut it's also possible to explicitly create new sections, which are visually delineated\nin the rendered documentation:\n\n```lua\n--- Special Functions.\n--\n-- Here we create a new section because of the `@section` tag below.  The first sentence\n-- of the comment block is the heading of the section, so it should be short and sweet,\n-- and it must end with a period (or some other sentence-ending punctuation like an\n-- exclamation point or question mark).\n--\n-- Anything that follows is text that is included under the section heading.  And of\n-- course *standard* **markdown** _is_ [supported](https://lua.org).\n--\n-- @section specialfuncs\n\n--- Now we're about to document a function.  The blank line just above is very important\n-- as it terminates the section block, and begins a new block, which will apply to\n-- the function below.\n--\n-- Now this function will appear within the Special Functions section, because that\n-- was the most recent collection element defined.  (It's possible to override which\n-- collection this function belongs to without changing the order in the code by\n-- using the @within tag.)\nfunction special()\nend\n```\n\n`@module` and `@class` are special types of collections called *top-level collections*.\nThis means they are given their own separate pages in the documentation, and also all\nelements they contain will have their fully qualified names to be scoped under the\ntop-level collection.\n\nFor example, a field `somefield` in a `@module somemodule` will be fully qualified as\n`somemodule.somefield`, which is how it can be referenced from documentation outside the\nmodule.  (`@section` is the exception here: section names are global, and it's up to\nyou to make them globally unique if you want to be able to reference them from other\npages in the documentation.)\n\n\n### Functions/Methods\n\nWhile Lua itself doesn't have explicit classes, LuaDox formalizes terminology such that in\n`@class` collections, functions are titled as **methods**, while for `@module` or `@table`\nthe term **function** is used.\n\nComment blocks preceding function definitions will add a new function to the current\ncollection, as seen in the earlier examples.  However it's also possible to define a\nfunction as an assignment:\n\n```lua\n--- This will be recognized as a function/method.\nxyz.some_function = function(a, b)\n   -- ...\nend\n```\n\n### Fields/Attributes\n\nDocumentation preceding an assignment where the rvalue is not a function is treated as a field.\nIn `@class` collections, fields are labeled as **attributes**.\n\nFields can be defined anywhere in code: globally, within tables, within functions, etc.  As long\nas there is a triple-dash documentation block that immediately precedes a non-function assignment,\nit will be added to the current collection as a field.\n\n```lua\n--- This will be recognized as a field/attribute\na = 42\n\nwhatever = {\n   --- This also works, but because \"whatever\" is not explicitly defined as a\n   -- table using the @table tag, this value here is exactly equivalent to the\n   -- above example.  In fact, LuaDox will actually log a warning here because\n   -- the lvalue \"a\" is redefined.\n   a = 42\n}\n```\n\nA special case is also handled where the lvalue of the assignment is in the form `self.attr = x`,\nspecifically when the lvalue is prefixed with `self.`.  Normally the fully qualified lvalue is\nincluded in the documentation, but with `self.attr` the `self` is stripped off and the `attr`\nis registered directly within the scope of the current top-level container.\n\nAnother special case specific to middleclass is in handling static fields.  When an attribute\ndefined in a `@class` collection contains the string `.static.` then it will be stripped out.\n\nThe example below demonstrates both these special cases:\n\n```lua\n--- This class does, well, something.\n-- @class xyz.Something\n-- @inherits xyz.Superclass\nxyz.Something = class('xyz.Superclass')\n\n--- Here the 'static' level will be automatically removed from the attribute name.\nxyz.Something.static.MYCONSTANT = 42\n\nfunction xyz.Something:initialize()\n    xyz.Superclass.initialize(self)\n    --- This is added as a field directly in the xyz.Something class.\n    self.answer = 42\nend\n```\n\nNote that documentation comments must immediately *precede* field definitions and\ncannot be on the same line:\n\n```lua\n--- Must precede the definition.\nfoo = 'bar'\n\n-- Meanwhile ...\nfoo = 'bar' --- This does NOT work.\n```\n\n## Reference Resolution\n\nReferences that aren't fully qualified (such as `@{this}`) are resolved based on\nthe scope where the reference was made.  The resolution rules are:\n1. Search fields or functions in the current collection\n2. If the current collection is a `@section` or `@table`, search up the scope\n   stack to the entire `@class` or `@module`\n3. Treat the reference as fully qualified, and search the global space for that\n   exact name\n4. If the top-level collection containing the reference is a `@class`, then search up\n   through the class hierarchy as established by `@inherits`\n\nWhen referencing a function, it's fine to include parens in the reference name.\nFor example `@{foo()}` or even just markdown inline code `foo()`.\n\n\n## Tags\n\nIt's first important to underline that LuaDox is not LDoc.  Many tags offered by LDoc are\nnot supported, while many new tags are introduced to provide additional functionality.\n\nMoreover, tags that do intersect between LDoc and LuaDox are not always implemented with\nthe same syntax or semantics, often because LuaDox extends their functionality.\nConsequently, you can expect a bit of a mess trying to pass LDoc-annotated code through\nLuaDox, especially when you've delicately structured your code so as to work around the\nmany quirks of LDoc.\n\nHere is a summary of LuaDox tags, with more details below the table:\n\n| Tag | Type | Description | Example |\n|-|-|-|-|\n| `@module` | Top-level collection | Declares a module and sets the scope for future documented elements. Modules, like all top-level types, are given separate pages in the rendered documentation. | `@module utils` |\n| `@class` | Top-level collection | Like `@module` but for classes, which are also given their own separate documentation pages. See also `@inherits`.  | `@class xyz.SomeClass` |\n| `@section` |  Collection | Organizes documented elements such as fields, functions, and tables into a visually distinct group with a heading and arbitrary preamble. Sections can't be nested within other sections; a `@section` tag always creates a *new* section within a top-level collection. | `@section utils.files` |\n| `@table` | Nested collection | Declares a new collection containing only fields (not functions like other collections), and allows nesting where field names are fully qualified based on the encapsulating table(s). In most common cases, `@table` isn't needed and `@section` will suffice. | `@table constants` |\n| `@inherits` | `@class` modifier | Indicates that the current class is subclassed from another class. This influences how references are resolved (superclasses are searched) and the rendered class page includes a visual of the class hierarchy. | `@inherits xyz.BaseClass` |\n| `@tparam` | Function modifier | Documents a typed parameter of the function definition that follows | `@tparam number\\|nil w the width of the image, or nil to derive it from height and aspect` |\n| `@treturn` | Function modifier | Documents a return value of the function definition that follows | `@treturn bool true if successful, false otherwise` |\n| `@see` | Section modifier | Adds a styled \"See also\" line linking to one or more space-delimited references | `@see ref1 ref2` |\n| `@type` | Field modifier | Documents the type of the field definition that follows | `@type table\\|nil` |\n| `@meta` | Field modifier | Documents arbitrary information for the field definition that follows | `@meta read/write` |\n| `@within` | Function/field modifier | Relocates the field or function to another collection while preserving its name. | `@within someothermodule` |\n| `@order` | Element modifier | Normally elements are documented in the order they appear in source, but `@order` allows changing the position of an element relative to other elements in the same rendered page. | `@order before somefunc` |\n| `@compact` | Collection modifier | Normally, fields and functions in a collection are shown first in summary table form and then broken out later with full documentation. `@compact` controls whether fields and/or functions should *only* show in tabular form. Useful for elements with smaller comments, such as a table of constants. Without arguments, both functions and fields will be shown in compact form, but you can specify `fields` or `functions` as an argument to compact just one of them. | `@compact fields` |\n| `@fullnames` | Collection modifier | Normally the table summary of fields and functions are not fully qualified, they are the unqualified short names. This tag ensures the table summary shows the fully qualified name. Commonly combined with `@compact` | `@fullnames` |\n| `@display` | Element modifier | Explicitly overrides the display name of an element, but does not affect its name for reference purposes. | `@display MyClass` |\n| `@rename` | Element modifier | Overrides *both* the display name and actual name of the element, affecting both its presentation in rendered pages as well as how the element is referenced. | `@rename different_function` |\n| `@scope` | Element modifier | Changes the scope of non top-level elements (i.e. functions, fields, and tables, but not classes or modules), affecting both the element's display name and reference name.  A special scope `.` can be used to treat the element as global and will prevent its name from being qualified by the collection it belongs to.  Unlike `@within`, the element is still documented in the same place (class or module page), but its fully qualified name will reflect the given scope name.   | `@scope .` |\n| `@alias` | Element modifier | Adds another name by which the element can be referenced. Does not affect the display name. | `@alias fooconsts` |\n| `@code` | Code block | Creates a code block with Lua syntax highlighting.  Any contents indented below the `@code` line will be included in the code block. | (See below.) |\n| `@example` | Code block | Like `@code` but adds an \"Example\" heading just above the code block | (See `@code`) |\n| `@usage` | Code block | Like `@code` but adds an \"Usage\" heading just above the code block | (See `@code`) |\n| `@note` | Admonition block | Creates a visually distinct text block, useful to highlight notable information. Contents indented below the `@note` tag are included in the block. Can contain nested blocks, such as code blocks or other admonitions. | (See below.) |\n| `@warning` | Admonition block | Like `@note` but uses a red color | (See `@note`)\n| `@field` | Element | Declare a field within a collection without an explicit field assignment in Lua code.  Rarely needed, and documenting field assignments is preferred and more flexible. Unlike LDoc, must *follow* `@table`. | `@field foo This is the description of the foo field` |\n| `@{name}` | Reference | Creates a link to the given element name, using `name` as the link text | `@{fileconsts}` |\n| `@{name\\|display text}` | Reference | Creates a link to the given element name, but uses `display text` the link text | `@{fileconsts|file constants}` |\n\n### `@module`\n\nDeclares a module, which creates a separate page in the rendered documentation, and begins\na new collections for all elements that follow.\n\nWhile uncommon, it's possible to have multiple `@module` tags in a single source file,\nwhich will result in multiple pages in the documentation.\n\n```lua\n--- Common utility functions.\n--\n-- @module utils\n```\n\n### `@class`\n\nDeclares a class, which, like `@module`, creates a separate page in the documentation, and\nis a collection for subsequent elements.\n\nSee also `@inherits`.\n\n```lua\n--- Class to manipulate images.\n--\n-- @class xyz.Image\n```\n\nAnd also like `@module`, it's possible to have multiple `@class` tags in the same file.\n\n### `@section`\n\nCreates a new section within a `@module` or `@class`.  Sections are given their own\nvisually distinct headings, and are collections for the fields and functions that follow.\n\nThe first sentence (terminated with a period, exclamation point, or question mark) is\nused as the section heading.  Anything past that is considered as section documentation\nbelow the heading.\n\n**The blank line(s) separating the `@section` block from the elements contained within the\nsection is necessary.**  This is how LuaDox knows where the documentation for the section\nends and the documentation for a new element (such as a field or function) begins.\n\n```lua\n--- Subclass API.\n--\n-- These functions are not strictly part of the public API, but can be used to create\n-- custom subclasses.\n--\n-- @section subclassapi\n\n--- Reset the state of the object.\nfunction xyz.Widget:_reset()\n   -- ...\nend\n```\n\n\n### `@table`\n\nCreates a new table collection, which is similar to `@section` but differs in three ways:\n1. Nested `@table` are supported, where fully qualified field names are based on the\n   full scope of all containing tables (e.g. `foo.bar.baz.field` where `foo`, `bar`, and\n   `baz` are nested tables).\n2. Only fields are shown. Functions are rendered in documentation as any other field.\n3. Unlike `@section`, a blank line isn't needed between the preamble documentation and\n   fields, because LuaDox knows to terminate the preamble as soon as the table\n   declaration begins.\n\n```lua\n-- xyz.os.\n--\n-- These fields are available immediately upon loading the `xyz` module.\n--\n-- @table xyz.os\n-- @compact\nxyz.os = {\n    --- true if running on Mac OS X, false otherwise\n    mac = (_os == 'osx'),\n    --- true if running on Windows, false otherwise\n    windows = (_os == 'win'),\n    --- true if running on Linux, false otherwise\n    linux = (_os == 'lin' or _os == 'oth'),\n}\n```\n\n### `@inherits`\n\nUsed within the context of a `@class` block to declare that the class has been derived\nfrom some other class.  The rendered HTML for the class page will include a tree showing\nthe full class hierarchy.\n\nThe `@inherits` tag takes a single argument that is the name of the immediate superclass.\n\n\n```lua\n--- @class xyz.Subclass\n-- @inherits xyz.BaseClass\n```\n\nUnqualified references made within the class documentation (all sections, fields,\nfunctions etc. for that class) will search for the name up the class's hierarchy.\nIf a name is defined in both the current class and one of the superclasses, the\nunqualified name will refer to the current class, and a fully qualified name must\nbe used to link to the superclass's field/function.\n\n\n### `@tparam`\n\nDefines a typed parameter for the function immediately following the comment block.  The\nformat of this tag is `@tparam \u003ctypes\u003e \u003cname\u003e \u003cdescription\u003e` where:\n * `\u003ctypes\u003e` is a pipe (`|`) delimited list of possible types, where the type name is\n   resolved to a link if possible\n * `\u003cname\u003e` is the name of the parameter from the function signature\n * `\u003cdescription\u003e` is everything that follows, and which can wrap on multiple lines\n   where subsequent lines are indented\n\n ```lua\n --- Clears the window to a specific color.\n --\n -- @tparam colortype|string|nil color the color to paint the window\n --    background, where nil is black\n function clear(color)\n     -- ...\n end\n```\n\nType names can refer to section names as well, which is a convenient way to document\ncustom complex types such as constants and enums (or Lua approximations thereof).  See the\n`seekconst` type from the example at the top of this page.\n\n\n### `@treturn`\n\nDefines a return value for the function immediately following the comment block.  The\nformat of this tag is `@treturn \u003ctypes\u003e \u003cdescription\u003e` where `\u003ctypes\u003e` and `\u003cdescription\u003e`\nare the same as that described for `@tparam`.\n\nMultiple `@treturn` tags can be used for functions that return multiple values.\n\n```lua\n--- Return the contents of the clipboard.\n--\n-- @treturn string|nil the clipboard contents, or nil if system clipboard\n--    is not available.\n-- @treturn string|nil the mimetype of the clipboard contents, or nil if\n--    clipboard not available.\nfunction get_clipboard()\n   -- ...\nend\n```\n\n### `@see`\n\nDisplays a \"See also\" line that links to one or more references.  The tag takes multiple reference\nnames separated by one space.  Function references can optionally include parens, but will always\nbe displayed with them.\n\n```lua\n--- @see xyz.Clipboard:get() get_clipboard() xyz.SomeClass\n```\n\nThis is slightly different from simply writing the line like \"See also `get_clipboard()`\"\nas it is wrapped in a div with class `see` that can be customized in CSS.\n\n### `@type`\n\nUsed in the comment block preceding a field definition and defines the field's type.  This\ntag takes the form `@type \u003ctypes\u003e` and, like `@tparam` and `@treturn`, the types argument\nis a pipe (`|`) delimited list of possible types, which will be resolved into links if\npossible.\n\nField types are shown both in the summary table as well as the full detailed field list.\n\n```lua\n--- If true, scrolling smoothly animates, while false scrolls in steps.  Nil will use the\n-- global default\n-- @type bool|nil\nsmooth_scroll = nil\n```\n\n### `@meta`\n\nLike `@type`, this is used in comment blocks preceding field definitions and can be used\nto communicate any arbitrary custom thing, however unlike `@type` it also works for\nfunctions.  This tag takes the form `@meta \u003canything\u003e` where `\u003canything\u003e` is a string that\nis allowed to contain spaces.\n\nThe meta value is displayed alongside any defined types via `@type` in both the summary\ntable as well as the detailed field list.\n\nA useful application of `@meta` is to indicate whether the field/attribute in question is\nconsidered read-only or read/write as far as the API caller is concerned.\n\n```lua\n-- The \"defaults\" table isn't meaningful here as far as documentation is concerned.\n-- This is just a regular comment, not a triple-dash documentation block, so LuaDox\n-- ignores it.  Fields defined and documented inside this table are added directly\n-- to the current collection.\ndefaults = {\n   --- The current width of the window which is updated when the user resizes the window.\n   -- @type number\n   -- @meta read-only\n   w = 640\n}\n```\n\n### `@within`\n\nCan be included in a documentation block preceding a function or field definition to relocate\nit to some other collection, while preserving the original name for display purposes.  The tag\ntakes the form `@within \u003cname\u003e` where `\u003cname\u003e` is the name of any collection, such as a\n`@class`, `@module`, or -- more usefully -- a `@section`, either in the same class or module,\nor some other.\n\nThis can be used to affect the location of a field or function in documentation without needing\nto reorder your code.  If you want exact control of the location relative to other fields or\nfunctions in that collection, you can use `@order`.\n\n```lua\n--- Called when the widget's position needs to be recalculated.\n-- @within subclassapi\nfunction xyz.Widget:_layout()\nend\n\n-- ... other stuff ...\n\n--- API available to subclasses.\n-- @section subclassapi\n```\n\nThis is a bit of a rare case, but if the collection being targeted by `@within` itself has a\n`@rename` tag, the collection name that `@within` needs to reference is the pre-renamed\nname of the target collection.\n\n### `@order`\n\nAffects where the element (whether field, function, table, or section) appears in the rendered\ndocumentation.  This isn't used to move a field or function to another collection -- use\n`@within` for that -- but it changes the location of the element relative to its siblings in\nthe collection.\n\nNon top-level collections (i.e. `@section` and `@table`) can also be reordered relative to one\nanother in the same module or class.\n\nThe tag takes the form `@order \u003cwhence\u003e [\u003canchor\u003e]` where `\u003cwhence\u003e` is one of:\n * `before`: moves the element *before* the given (fully qualified) anchor element\n * `after`: moves the element *after* the given (fully qualified) anchor element\n * `first`: make the element the first one in the collection (and where `\u003canchor\u003e` is not needed)\n * `last`: makes the element the last one in the collection (and where `\u003canchor\u003e` is not needed)\n\n ```lua\n --- Draws the widget.\n -- @within subclassapi\n -- @order after xyz.Widget:_layout\nfunction xyz.Widget:_draw()\nend\n```\n\n### `@compact`\n\nCollections include a summary table of fields and functions within the collection, where\neach element includes only the first sentence from their documentation, before enumerating\nthe full list of elements with their full documentation blocks below the summary table.\n\nThe `@compact` tag is used to skip the more detailed list, showing only the tabular form.\nIn this case, the full documentation is included in the table, not just the first sentence.\n\nThe tag takes an optional argument, either `field` or `function` that skips the full detailed\nlist for one or the other type of element.  If the argument is omitted, both fields and\nfunctions are shown only in tabular form.\n\nSee `@fullnames` below for a combined example.\n\n### `@fullnames`\n\nNormally a collection's table summary of fields and functions displays the unqualified\nshort name. This tag, which takes no arguments, causes the table view to display the fully\nqualified name instead.\n\n```lua\n--- Seek constants.\n--\n-- These constants can be used with `seek()`.\n--\n-- @section seekconst\n-- @compact\n-- @fullnames\n\n--- Seek from the beginning of the file.\nxyz.File.static.SEEK_SET = 'set'\n--- Seek from the current position.\nxyz.File.static.SEEK_CUR = 'cur'\n--- Seek to the end of the file.\nxyz.File.static.SEEK_END = 'end'\n```\n\n### `@display`\n\nAffects how the element is displayed in documentation, but doesn't alter how the element\nis referenced.  This tag takes the form `@display \u003cname\u003e` where `\u003cname\u003e` is the overridden\ndisplay name.\n\nOne use case is to change the name of middleclass initializers, where the class is invoked\ndirectly to construct a new instance:\n\n```lua\n--- Creates a new widget with the given attributes.\n-- @display xyz.Widget\nfunction xyz.Widget:initialize(attrs)\n```\n\n### `@rename`\n\nLike `@display` in that it changes the element's display name in documentation, but *also* changes\nthe name for references.\n\n### `@scope`\n\nElement names are normally qualified based on their containing class, module, or table.\nFor example, a field `bar` defined in a `@class Foo` would be fully qualified as\n`Foo.bar`. However, the `@scope` tag can override the containing scope -- `Foo` in this\ncase -- with any arbitrary symbol.  This affects how the element is both displayed and how\nit's referenced, however doesn't change which collection the element appears in. (Use\n`@within` for that.)\n\nThe tag takes the form `@scope \u003cname\u003e` where `\u003cname\u003e` replaces the element's normal scope name.\nA special scope `.` (single dot) will treat the element as global, preventing it from being\nqualified by anything: the field or function will be considered as global both in how it's\ndisplayed and referenced.\n\n```lua\n--- Miscellaneous utilities.\n-- @module utils\n\n--- Normally this field would be qualified as utils.MYCONST, but this makes it appear\n-- as a global value, and can be referenced elsewhere as @{MYCONST}\n-- @scope .\nMYCONST = 42\n```\n\n### `@alias`\n\nAdds another name by which the element can be referenced elsewhere in documentation.  The\ndisplay name is unchanged, and the element's normal name can still be used for references.\nThis merely adds an additional name for references.\n\n\n### `@code`\n\nRenders a fenced code block with syntax highlighting in the documentation.  The tag takes\nan optional argument that dictates the syntax highlighting language, which defaults to\n`lua` when not specified.\n\nAny commented lines indented within @code are included in the markdown code block. The\ncode block terminates as soon as a line has less indentation than the first line under the\n`@code` tag.\n\n```lua\n--- Some function to do a thing.\n--\n-- This might be some example usage:\n-- @code\n--    -- This is actually a comment in the code block.\n--    -- Subsequent lines indented at this level are included in the block.\n--    local x = do_a_thing()\n--\n-- Now that this line is indented less than the first line under @code, this will\n-- *not* be included in the code block, but will start a new paragraph underneath\n-- it. The blank line separating this paragraph and the code block isn't significant,\n-- only the indentation level matters.\nfunction do_a_thing()\n    -- ...\nend\n```\n\n### `@example`\n\nLike `@code`, and works exactly the same way in terms of the semantics of indendation, but adds a\nheading Example\" above the syntax-highlighted code block.\n\n### `@usage`\n\nLike `@example`, but the heading says \"Usage\" instead.\n\n### `@note`\n\nCreates a visually distinct paragraph (bordered with a green background color), which can\nbe used to emphasize noteworthy content.\n\nThis tag takes the form `@note \u003ctitle\u003e` where `\u003ctitle\u003e` is an *optional* arbitrary string\n(which can include spaces) that acts as the title of the block.  Indentation controls the\ncontents of the block, exactly as `@code` works.\n\nNesting is possible, including (and most usefully) `@code` blocks which can appear\nwithin admonitions.\n\n\n```lua\n--- This is the start of a normal documentation block.\n--\n-- Some standard documentation content would go here.\n--\n--  @note This is the title of the block\n--    Now anything indented at this level is included within the admonition paragraph.\n--    That includes this line, but not the next one.\n--\n--    @code\n--       -- This is a nested code block inside the note.\n--       foo()\n--\n-- This line is dedented relative to the first line under @note so it starts a normal\n-- paragraph at the same level as the first one.\n```\n\n### `@warning`\n\nExactly like `@note` but uses a red background instead of green so is useful for warning\nor cautionary content.\n\n### `@field`\n\nAdds a field to the current collection purely a comment, without the need for a line of\nLua code to declare and assign the field.\n\nThis tag takes the form `@field \u003cname\u003e \u003cdescription\u003e` where `\u003cname\u003e` is the name of the field\nand `\u003cdescription\u003e` is an arbitrary, single line description of the field.\n\n```lua\n--- @field level The current log level.\n```\n\nThe above is semantically equivalent to this:\n\n```lua\n--- The current log level.\nlevel = nil\n```\n\nGenerally the second form above is preferred, because it allows for multiple lines and\neven paragraphs of comments, as well as field modifiers such as `@type` and `@meta`.\n\nUnlike LDoc, `@field` must follow a `@table` definition:\n\n```lua\n--- Current mouse state.\n-- @table mouse\n-- @field x the x coordinate of the cursor\n-- @field y the y coordinate of the cursor\n-- @field button the current mouse button pressed\n```\n\n### Reference tags\n\nReference tags are used to create hyperlinks in the rendered documentation to any element\nin any file.  Reference tags can take either of these forms:\n1. `@{name}`: resolve `name` per the reference resolution rules described earlier, and use\n   the fully qualified form of the reference name as the link text (even if `name` itself\n   is not fully qualified)\n2. `@{name|link text}`: resolve `name` but use the given `link text` instead of the\n   fully qualified name of the reference.\n\nAlthough not a tag, if the contents of markdown `inline code` is a resolvable name, it\nwill be rendered as a hyperlink (still with preformatted text), but unlike `@{name}` which\nuses the fully qualified form, the with `inline code` the hyperlink text will be as\nwritten.\n\n## Manual Pages\n\nArbitrarily many separate custom markdown files can be included in the rendered\ndocumentation. They are defined in the `[manual]` section of the config file, or can be\npassed using the `-m` or `--manual` command line argument.\n\nEach document is defined in the form `id=filename.md` where `id` is the top-level scope\nname for reference purposes (see later), and also dictates the name of the rendered html\nfile.\n\nConsider this configuration, for example:\n\n```\n[manual]\nindex=intro.md\ntutorial=tut.md\n```\n\nThis will add both pages to the manual.  **index** is a special id, which is written\nas the root `index.html` in the rendered documentation, and is also linked from the\ntopbar on every page.\n\nSuppose our `intro.md` looked like:\n\n```markdown\n# Introduction\n\nSome introductory paragraph.  By the way, images are supported:\n\n![](img/foo.png)\n\nThe image is relative to the path of the current file.  It's up to you to\ncopy the `img/` directory to the rendered documentation output directory\nafter.\n\n## How to install\n\nThis is a preamble paragraph on installation.\n\n### Linux\n\nHow to install on Linux ...\n\n### OS X\n\nHow to install on a Mac ...\n\n### Windows\n\nSorry about your luck ...\n\n#### This is a level 4 heading\n\nNothing very interesting here.\n```\n\nWithin the markdown, the level 1 heading dictates the title of the manual page, which\nis used in the Manual section of the sidebar, as well as the HTML title for the manual\npage.  In the above example, that's \"Introduction\".\n\nLevel 2 and level 3 headings are included in the table of contents in the sidebar.\n\n### References and Manual Pages\n\nThe manual page id (e.g. `index` and `tutorial` in the example above) is the top-level\nsymbol.  You will want to make sure you pick an id that doesn't conflict with any\n`@module` or `@class` name from the documentation, as these all share the top-level\nnamespace.\n\nLevel 1, 2, and 3 headings are names subordinate to the id, and are converted to slugs by\nconverting everything to lowercase, removing all punctuation, and replacing spaces with\nunderscores.\n\nFor example, `index.how_to_install` or `index.linux`.  This name can be referenced from\ncode, and also other manual pages.  The `@{name}` and `@{name|link text}` reference tags\nare supported in manual pages as well.\n\n\n## Execution\n\nLuaDox is distributed as a single binary that can be downloaded [on the release\npage](https://github.com/jtackaberry/luadox/releases/latest).  On Linux and OS X, the\nbinary can be executed directly:\n\n```bash\n$ luadox -c luadox.conf\n```\n\nBut on Windows, Python must be called directly (and of course this also works on\nLinux and OS X):\n\n```\nC:\\src\\luadox\u003e python luadox -c luadox.conf\n```\n\n`luadox --help` will output usage instructions:\n\n```\nusage: luadox [-h] [-c FILE] [-n NAME] [-o DIRNAME] [-m [ID=FILENAME [ID=FILENAME ...]]]\n              [--css FILE] [--favicon FILE] [--nofollow] [--encoding CODEC] [--version]\n              [FILE [FILE ...]]\n\npositional arguments:\n  [MODNAME=]FILE        List of files to parse or directories to crawl\n                        with optional module name alias\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -c FILE, --config FILE\n                        Luadox configuration file\n  -n NAME, --name NAME  Project name (default Lua Project)\n  -o DIRNAME, --outdir DIRNAME\n                        Directory name for rendered files, created if necessary (default ./out)\n  -m [ID=FILENAME [ID=FILENAME ...]], --manual [ID=FILENAME [ID=FILENAME ...]]\n                        Add manual page in the form id=filename.md\n  --css FILE            Custom CSS file\n  --favicon FILE        Path to favicon file\n  --nofollow            Disable following of require()'d files (default false)\n  --encoding CODEC      Character set codec for input (default UTF-8)\n  --version             show program's version number and exit\n```\n\nThe positional `[MODNAME=]FILE` argument(s) defines what source files to scan.  The\n`FILE` part can be either specific Lua source files, or directories within which\n`init.lua` exists.  By default, LuaDox will follow and parse all files that are\n`require()`d within the code, provided the required file is discovered within any of the\ndirectories containing the files passed on the command line.\n\nThe optional `MODNAME` part of the argument explicitly specifies the Lua module name as\n`require()`d in code.  For example, if your library is called `foo` and your source files\nare held in `../src/foo` then LuaDox knows that when requiring `foo.bar.baz` from Lua, we\nshould check `../src/foo/bar/baz.lua` because of the matching `foo` component between the\nmodule name and the path.\n\nHowever, if all your source files for module `foo` were instead contained in `../src`,\nsay, you need to tell LuaDox that requiring `foo.bar` is actually at `../src/bar.lua`.\nThis is done by specifying `MODNAME` in the argument, i.e. `foo=../src`.\n\nBottom line: if your directory structure is directly named after the module name, you\nprobably don't need to specify the `MODNAME` alias, but if your directory is called\nsomething else, like `src`, you do.\n\nThe behavior to automatically discover and parse `require()`d files can be disabled with\nthe `--nofollow` argment or setting `follow = false` in the config file, in which case\nLuaDox will only parse files explicitly passed.\n\nMost options can be defined on the command line, but it may be more convenient to\nuse a config file.\n\nConfig files are ini-style files that define these sections:\n* `[project]` for project level settings\n* `[manual]` for manual pages where each page is a separate `id=filename` line\n* `[link\u003cn\u003e]` for user-defined custom links that appear on the center of\n   each page, and where `\u003cn\u003e` is a number that controls the order.\n\nHere's an annotated example `luadox.conf` that describes the available config\nproperties.  All properties are optional except for files (although files could\nalso be passed on the command line if you prefer).\n\n```ini\n[project]\n# Project name that is displayed on the top bar of each page\nname = My Lua Project | Where Awesome Things Happen\n# HTML title that is appended to every page. If not defined, name is used.\ntitle = My Lua Project\n# A list of files or directories for LuaDox to parse.  Globs are supported.\n# This can be spread across multiple lines if you want, as long as the\n# other lines are indented.\nfiles = ../app/rtk/widget.lua ../app/rtk/\n# The directory containing the rendered output files, which will be created\n# if necessary.\noutdir = html\n# Path to a custom css file that will be included on every page.  This will\n# be copied into the outdir.\ncss = custom.css\n# Path to a custom favicon. This will be copied into the outdir.\nfavicon = img/favicon.png\n# If require()d files discovered in source should also be parsed.\nfollow = true\n# Character encoding for input files, which defaults to the current system\n# locale.  Output files are always utf8.\nencoding = utf8\n\n[manual]\n# Custom manual pages in the form: id = filename.\n#\n# The ids must not conflict with any class or module name otherwise references\n# will not properly resolve.\nindex = intro.md\ntutorial = tut.md\n\n[link1]\nicon = download\ntext = Download\nurl = {root}index.html#download\n\n[link2]\nicon = github\ntext = GitHub\nurl = https://github.com/me/myproject\n```\n\nLink sections are optional. Each section takes these options:\n * `text` (required): the link's text\n * `url` (required):\n * `icon` (optional): the name of a built-in icon, or path to a custom image file.\n     Currently supported built-in icon names are `download`, `github`, `gitlab`, and\n     `bitbucket`.  If the value isn't one of the built-in names then it's treated as\n     a path, where `{root}` will be replaced with the relative path to the document\n     root.\n * `tooltip` (optional): the tooltip text that appears when the mouse hovers over\n    the hyperlink.\n\nUser-defined links currently can't be specified on the command line, they must\nbe defined in the config file.\n\n## Docker Image\n\nLuaDox is also available as a [Docker image on Docker Hub](https://hub.docker.com/r/jtackaberry/luadox):\n\n```bash\n$ docker run -v ~/src/myproject:/project -w /project/doc jtackaberry/luadox luadox -c luadox.conf\n```\n\nOf course, that's a bit cumbersome, having to set up the volume mount and\nworking directory, so for command line use the release binary is probably more\nconvenient.  However the Docker image can be useful when generating\ndocumentation as part of a CI/CD pipeline, such as GitHub Actions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjtackaberry%2Fluadox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjtackaberry%2Fluadox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjtackaberry%2Fluadox/lists"}