mirror of
https://github.com/FlightControl-Master/MOOSE.git
synced 2025-08-15 10:47:21 +00:00
95 lines
4.3 KiB
Markdown
95 lines
4.3 KiB
Markdown
---
|
|
parent: Build system
|
|
grand_parent: Developer
|
|
nav_order: 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:<br/>
|
|
<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:<br/>
|
|
<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.
|
|
|
|
# Build a preview locally
|
|
|
|
To generate a preview of the class documentation go into the folder
|
|
`docker/build-docks` and run `docker compose up`. It will create a Docker image
|
|
and start a Docker container. Within this container all needed software packages
|
|
are included to build to class documentation.
|
|
|
|
- You need a working installation of [Docker].
|
|
- In the main repository folder a new folder `build` will be created.
|
|
- Subfolders `build/docs` and `build/tools` will be generated.
|
|
- Repo `Applevangelist/luadocumentor` will be checked out to `build/tools/luadocumentor`
|
|
- `luadocumentor.lua` will be executed and writes the output to `build/docs`.
|
|
|
|
{: .note }
|
|
> If [MOOSE_DOCS] is checked out to `/moose/build/MOOSE_DOCS` by the developer
|
|
> manually, then the generated files are also copied into `/moose/build/MOOSE_DOCS/Documentation/`.
|
|
> This allows to run `docker compose up` in `/moose/build/MOOSE_DOCS/docker/`,
|
|
> so the full result can be checked.
|
|
|
|
[tree]: https://wiki.ubuntuusers.de/tree/
|
|
[LuaDoc]: https://keplerproject.github.io/luadoc/
|
|
[LuaDocumentor]: https://luarocks.org/modules/luarocks/luadocumentor
|
|
[Applevangelist/luadocumentor]: https://github.com/Applevangelist/luadocumentor/tree/patch-1
|
|
[markdown]: https://luarocks.org/modules/mpeterv/markdown
|
|
[penlight]: https://luarocks.org/modules/tieske/penlight
|
|
[metalua-compiler]: https://luarocks.org/modules/luarocks/metalua-compiler
|
|
[metalua-parser]: https://luarocks.org/modules/luarocks/metalua-parser
|
|
[checks]: https://luarocks.org/modules/fab13n/checks
|
|
[MOOSE]: https://github.com/FlightControl-Master/MOOSE
|
|
[MOOSE_DOCS]: https://github.com/FlightControl-Master/MOOSE_DOCS
|
|
[MOOSE_DOCS_DEVELOP]: https://github.com/FlightControl-Master/MOOSE_DOCS_DEVELOP
|
|
[Lua]: https://www.lua.org/
|
|
[LuaRocks]: https://luarocks.org/
|
|
[.github/workflows/build-docs.yml]: https://github.com/FlightControl-Master/MOOSE/blob/master/.github/workflows/build-docs.yml
|
|
[Docker]: https://www.docker.com/
|