MOOSE/docs/developer/buildsystem/build-docs.md

parent, grand_parent, nav_order

parent	grand_parent	nav_order
Build system	Developer	2

Build class documentation

The documentation of all classes are included in the code as comments. This kind of documentation process is called LuaDoc. But we build the html files for the documentation with LuaDocumentor. It is a tool similar to LuaDoc, but with some additional features the Moose team decided to use.

{: .important }

The team created also some modifications, which are not part of the official LuaDocumentor tool. So we use the code in the git repository Applevangelist/luadocumentor in the branch patch-1.

There are two git repositories which are used to save the generated documentation:

• MOOSE_DOCS is the repository for the master branch of MOOSE
  • A configured GitHub Pages job will deploy the result to:
    https://flightcontrol-master.github.io/MOOSE_DOCS/
• MOOSE_DOCS_DEVELOP is the repository for the develop branch of MOOSE
  • A configured GitHub Pages job will deploy the result to:
    https://flightcontrol-master.github.io/MOOSE_DOCS_DEVELOP/

Main build steps to create the class documentation are defined in .github/workflows/build-docs.yml:

• Checkout of the git repository MOOSE.

• Create output folders.

• Checkout of the git repository Applevangelist/luadocumentor with branch patch-1 into a subdirectory.

• Update the Linux system software.

• Install needed tools:

  • tree - A tool to output a tree view of a folder structure.
  • lua - Package to run Lua scripts. This time Lua 5.1, because it matches the DCS environment.
  • LuaRocks - This is the package manager for Lua modules.
  • markdown - Dependency for LuaDocumentor
  • penlight - Dependency for LuaDocumentor
  • metalua-compiler - Dependency for LuaDocumentor
  • metalua-parser - Dependency for metalua-compiler
  • checks - Dependency for metalua-parser

• Run the build steps:

  • Run luadocumentor.lua to create the html files.

• Deploy build results:

  • Checkout MOOSE_DOCS or MOOSE_DOCS_DEVELOP git repository in a subdirectory.
    • Use the matching git repository for the branch of MOOSE.
      • master -> MOOSE_DOCS.
      • develop -> MOOSE_DOCS_DEVELOP.
    • Use a TOKEN for checkout, so a push is possible later on.
  • Copy build result to MOOSE_DOCS folder.
  • Push results to the target repository.