The documentation is currently presented in a series of markdown files directly in the GitHub page. Serving the documentation from within the app would have these advantages:
- The documentation would be more at hand.
- Some parts of the documentation are already dynamically generated into the static markdown files during the build, this could be improved.
- Better presentation of code examples
- Perhaps code on the left, mlog output on the right
- The examples would be kept is separate files and would be compiled during build (unit tests), difference from the expected output would be inspected, as
- all examples should always correspond to current compiler output,
- when the output of the example changes, it needs to be reviewed - it might indicate an error, or maybe changes to the compiler/optimizer changed the output in such a way it no longer serves the purpose of the example.
- Additional dynamic contents
- List of keywords
- List of Mindustry contents (items, liquids, units, building types, sounds, ...)
- List of experimental and deprecated features (?)
- Needs to have support for configurable redirects when the structure of the documentation changes.
- Optional enhancements
- The source code and output might be integrated with the compilation engine and allow altering and compiling the examples in place
Things that needs to be figured out:
- The primary format of the documentation to be rendered on the web page (maybe slightly enhanced markdown?)
The documentation is currently presented in a series of markdown files directly in the GitHub page. Serving the documentation from within the app would have these advantages:
Things that needs to be figured out: