diff --git a/docs/developer/buildsystem/build-docs.md b/docs/developer/buildsystem/build-docs.md index 4857f6836..d9ae9ea3b 100644 --- a/docs/developer/buildsystem/build-docs.md +++ b/docs/developer/buildsystem/build-docs.md @@ -57,6 +57,25 @@ Main build steps to create the class documentation are defined in [.github/workf - 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 @@ -72,3 +91,4 @@ Main build steps to create the class documentation are defined in [.github/workf [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/ diff --git a/docs/developer/buildsystem/build-includes.md b/docs/developer/buildsystem/build-includes.md index 83c91a21c..a7b3e21d1 100644 --- a/docs/developer/buildsystem/build-includes.md +++ b/docs/developer/buildsystem/build-includes.md @@ -22,8 +22,8 @@ Main build steps to create the include files are defined in [.github/workflows/b - Run the build steps: - Run `./Moose Setup/Moose_Create.lua` to create `Moose.lua`. - - Run `./Moose Setup/Moose_Create.lua` to create dynamic `Moose.lua` to - load individual Lua class files used by Moose developers. + - Run `./Moose Setup/Moose_Create.lua` to create dynamic `Moose.lua` which + loads individual Lua class files used by Moose developers. - Run [LuaSrcDiet] to compress the [Lua] code and create `Moose_.lua` - Run [LuaCheck] to find errors in the code. Warnings are ignored, because there are a lot of warnings, which cannot be resolved by the Moose team. @@ -35,6 +35,23 @@ Main build steps to create the include files are defined in [.github/workflows/b - Copy build result to `MOOSE_INCLUDE` folder - Push results to [MOOSE_INCLUDE] repository +# Build a preview locally + +To generate a preview of the include files go into the folder +`docker/build-includes` 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 the +include files. + +- You need a working installation of [Docker]. +- In the main repository folder a new folder `build` will be created. +- The following subfolders will be generated: + - `build/result/Moose_Include_Dynamic` and + - `build/result/Moose_Include_Static` +- `./Moose Setup/Moose_Create.lua` will be executed to generate the target files +- [LuaSrcDiet] will be executed to generate the target file `Moose_.lua` +- [LuaCheck] runs to find errors + [.github/workflows/build-includes.yml]: https://github.com/FlightControl-Master/MOOSE/blob/master/.github/workflows/build-includes.yml [tree]: https://wiki.ubuntuusers.de/tree/ [lua5.3]: https://www.lua.org/manual/5.3/ @@ -44,3 +61,4 @@ Main build steps to create the include files are defined in [.github/workflows/b [MOOSE_INCLUDE]: https://github.com/FlightControl-Master/MOOSE_INCLUDE [LuaSrcDiet]: https://github.com/jirutka/luasrcdiet [Lua]: https://www.lua.org/ +[Docker]: https://www.docker.com/ diff --git a/docs/developer/buildsystem/gh-pages.md b/docs/developer/buildsystem/gh-pages.md index 4bfa70bfd..fc957d339 100644 --- a/docs/developer/buildsystem/gh-pages.md +++ b/docs/developer/buildsystem/gh-pages.md @@ -38,6 +38,20 @@ This can be displayed as follows: - Open a browser with the following URL: `http://127.0.0.1:4000/`. - After a change of the [Markdown] files, wait some seconds and press F5 in the browser. +{: .warning } +> Some changes are not processed properly with this procedure. It is then +> necessary to stop and restart the container once. On startup everything is +> always regenerated. + +# Run linkinator to find brocken links + +When changing this documentation it is very useful to run linkinator to find broken links. +This can be done as follows: + +- You need a working installation of [Docker]. +- Go to the `docker/gh-pages-check` subfolder. +- Run `docker compose up`. + [GitHub Pages]: https://pages.github.com/ [MOOSE]: https://github.com/FlightControl-Master/MOOSE [Just the Docs]: https://github.com/just-the-docs/just-the-docs