LuaAutoDoc 0.9.1

Generates full HTML documentation of a Lua project with LuaDoc tags.

LuaAutoDoc

A simple cross-platform documentation generator for Lua based on established LDoc tags. The script uses pure python 3.10 and will generate full documentation for your project based on your doc tags. The script is designed to be as simple as possible to run and only requires python 3.10 or later to be installed to get started.

Installation

1. If you do not have python3.10 or later installed, you can install the latest version here: https://www.python.org/downloads/
2. Once installed, install the LuaAutoDoc module with pip: pip install LuaAutoDoc

Usage

A Basic usage example, use LuaAutoDoc --help for more detailed information about available commands and options, or check out the ExampleProject for a detailed example of you can use the tool in a project.

1. Open up your project in the terminal and call LuaAuoDoc init. This will create a LuAutoDoc/ folder in your project. Inside you will find a simple configuration file where you can fill in authorship, lua version, whether to hide the source code or not, etc...
2. After having customised the configuration file, call LuaAutoDoc build -s and your documentation will be generated. By default, the documentation will be generated in a new folder DocBuild/ at the top level of your project, this can be changed in the configuration file.

Recommended actions after initialisation

After calling LuaAutoDoc init you will have two html files in LuaAutoDoc/HTMLFragments/:

Mandatory_user_data.html contains the front page description of your documentation. Here you should add your text about the project and any other information you want to be displayed on the front page.

CustomNavbar.html Can be changed to add links to extra pages in the navbar. E.g. if you want separate pages for a tutorial, changelog, installation guide, etc... Take a look at the ExampleProject for an example of how to add lists to the navbar.

You can get a template for custom pages that keeps the look and style of the rest of the documentation by calling LuaAutoDoc template --html

Syntax rules

1. Docstrings starts with triple dash --- and ends with a line terminator.
2. All tags start with ---@{tag} and are followed by whitespace.
3. All tags are case-sensitive. Whitespace between --- and @ is allowed and left to the user's preference.
4. All docstrings must be placed directly above the class or function they are describing.
5. Empty lines or comments between docstrings are not allowed.
6. Class methods must be defined after the class and in the same file as the class definition. This is a requirement as the script has no guarantee that the user do not have multiple classes with the same name in different files.

Supported Tags

The {} brackets are not a part of the tag syntax, they are only here to show the different components of a tag.

• Description is implicitly assumed for any docstrings without an explicit tag. For those who want to be explicit, --- @description {description} is supported. Multiple lines of descriptions is supported though whitespace at the start and end of each line is not preserved except for a single space where there is a newline. New lines can be inserted with \n. Likewise, tabs can be inserted with \t.
• @usage - A special form of description, this is meant as a short description of the usage of the class or function.
  Format: --- @usage {description}
• @module - Assigns all classes and functions appearing below it to a given module. The tag must be separated with at least one empty line from a docstring belonging to a class or function as the script will look for @see, @internal, @deprecated and description docstrings below a module tag. The tag can be useful for those wishing to bundle classes and functions from multiple files into one place in the documentation.
  Format: --- @module {module_name}
• @ignoreFile - Marks the file to be ignored by the script.
  Format: --- @ignoreFile
• @author - Assigns a module, class or function to a specific author. Author(s) for the full project should be assigned in Config_LuaAutoDoc.py.
  Format: --- @author {author_name}
• @class - Assigns the following entry to a class. This tag is only optional (but still recommended) if @field, @member or @superclass are used are used.
  Format: --- @class {class_name} : {super_class}
• @superclass - Assigns a superclass to a class. You can also provide a hint to script of the superclass if you have classes with duplicate names. Supported hints are:
  • \[abs_path: {path}] - Will tell the script which file to search for the entry.
  • \[rel_path: {path}] - Will tell the script which file to search for the entry, relative to the configured project root folder.
  • \[module: {module_name}] - Will tell the script which module to search for the function.
  When trying to detect the correct reference, the script will search in the order: file -> module -> project.
  Format: --- @superclass {superclass_name} {link_hint}(optional)
• @field - Assigns a field to a class. Alternative tags with equal result are @member and @param. Appending ?=default_value to the end of the field_name will tag the parameter as optional with default_value as the default value, if =default_value is omitted with only ? appended, it will be assumed to be nil.
  Format: --- @field {field_name}{?=default_value} {field_type} {description}
• @property - Assigns a constant field to a class. This should be used for any const values your class holds.
  Format: --- @property {property_name} {value}
• @member - See @field
• @param - Assigns a parameter to a function. @member and @param will also work, but are discouraged for functions. Appending ?=default_value to the end of the param_name will tag the parameter as optional with default_value as the default value, if =default_value is omitted with only ? appended, it will be assumed to be nil.
  Format: --- @param {param_name}{?=default_value} {param_type} {description}
• @return - Assigns a return value to a function. Appending ?=default_value to the end of the return_type will tag the return value as optional with default_value as the default value, if =default_value is omitted with only ? appended, it will be assumed to be nil.
  Format: --- @return {return_type}{?=default_value} {description}
• @raise - Assigns an exception that the function may raise. This tag can be used multiple times to add multiple exceptions.
  Format: --- @raise {exception_name} {error_level} {description}
• @deprecated - Marks a class or function as deprecated, will give a warning in the documentation to discourage use.
  Format: --- @deprecated {description}
• @internal - Marks a class or function for internal use only, and should not be used by the end user. This will mark the entry with a warning in the documentation.
  Format: --- @internal {description}
• @hidden - Marks the class or function to not be included in the documentation. This tag can be made more specific by adding "tags" to the tag. This allows you to "un-hide" parts of the hidden code by adding tag exemptions to the config file, these tags are optional. You can ignore all @hidden tags by setting the show_hidden option in the config file to "True"
  Format: --- @hidden {tags seperated by space}
• @ignore - While similar to @hidden, this tag can not be given identifiers like @hidden, nor can it be turned off in the config file. From a backend perspective, entries with the @ignore are effectively non-existent vs @hidden which may still be identified by references and end up leading to a dead link. This tag may be necessary if you have multiple @class definitions in the same file, which may be a requirement for some documentation extensions like the VSCode extension "Lua" by sumneko.
  Format: --- @ignore
• @see - Adds a hyperlink. Functions, classes, class methods and modules will be automatically detected. If you want alternate text to be shown for the link (mostly useful for weblinks to hide the url), you can supply an optional argument [link_text: text] the tag. Use \] to escape closing square bracket if it's part of the text. To ensure entries are interpreted correctly (in case of duplicate names), an optional argument {link_hint} can be supplied. Supported hints are:
  • \[abs_path: {path}] - Will tell the script which file to search for the entry.
  • \[rel_path: {path}] - Will tell the script which file to search for the entry, relative to the configured project root folder.
  • \[module: {module_name}] - Will tell the script which module to search for the function.
  When trying to detect the correct reference, the script will search in the order: file -> module -> project.
  Alternatively you can link to a webpage, webpage links are detected by starting with https:// or http://
  This tag can be used multiple times to add multiple links, and inside description docstrings for inline references
  Format: --- @see {link} [link_text: 'text'](optional) {link_hint}(optional) {description}
  or: --- @description {~fluff~} --- @see {link} [link_text: 'text'](optional) {link_hint}(optional) {~fluff~}

Error codes

• SCH-0 - SourceCodeHighlighter.py could not locate SourceCodeMirror.html is either missing or your Config_LuaAutoDoc.py is misconfigured, and you have the wrong path stored in the setting html_fragment_directory points to the wrong folder.
• SCH-1 - The built-in highlighter for Lua code raised an error while indexing and applying tags to the code. This may happen if the code contains invalid or less common syntax, or might be an unrelated bug altogether. This error should be reported to the developer here.
• SCH-2 - When creating source code mirror files, each html is given a unique name based on their original filename and a 10 letter string based on a sha1 hash of their path. This makes filename collisions "unlikely". However, if the script detects an existing file with the same filename, it will raise an error to stop documentation. Running the script should clear out the destination folder before writing, if this process is hindered it may be the cause of the error.
• LDP-0 - LuaDocParser.py detected a class being extended by another class, but could not identify the class and superclass. Unless you declared a superclass with @superclass the parser was unable to identify the superclass. Consider adding @superclass to the class docstring if your class extends another class.
• LDP-1 - A docstring was detected right below a module tag, but docstring did not match a description tag. Since @module only supports the description tag below it, you must separate other docstring types with at least one empty line.
• DC-0 - An unknown docstring tag was detected. The line will simply be ignored by the parser, but the user may want to investigate if they are losing data they want in their documentation.
• DC-1 - An unknown doc entry got through the parser. This is most likely a bug in the parser, and should be reported to the developer here.
.
• FR-0 - A LuaAutoDoc tag was requested, but was not found. Check the configured html_directory that the requested tag exists and follows the rules for LuaAutoDoc tags.
• FR-1 - A html file was requested, but it could not be found in the configured html directory, nor the packaged html directory. This error should only show up if the user have deleted files in the pip package. Re-downloading the module should fix this error.
• DM-0 - When looking for a href for a DocEntry's parent, the parent was not found in the data_object. This is most likely caused by a misspelling in the @superclass tag, or a bug in the parser. This error should be reported to the developer here if @superclass is entered correctly.
• DM-1 - A tag was not caught and resolved by the tag mapper. This is most likely a bug in the tag mapper, and should be reported to the developer here.
• DM-2 - If you have not messed around with LuaAutoDoc tags in your html files, this a bug that should be reported. If you have used the LuaAutoDoc tags #LuaAutoDoc-GetValue this would be the source of your issue. This tag can only be safely called from pre-defined LuaAutoDoc tags that already calls it.
• DM-3 - When creating html files, LuaAutoDoc encountered a pre-existing file when trying to create a new file. This should in theory almost certainly never happen, but if it does, it is possible that you got two filenames with identical names and which paths happen to resolve in to the same 10 letter sha1 hash. A more likely scenario is that there is something wrong with the script and should be reported if not a hash collision.
• INDEX-0 - If you encounter this error it means the author have messed up badly in an update, please report here as soon as possible.

Note: The fonts included in this project have their own licenses, you can read them in the Assets folder.