New combined manual format – feedback wanted!

General
1

Hi everyone,

I’ve been working on improving the documentation. Until now we had:

  • a single-page manual that was hard to navigate, and
  • a separate multi-page Lua scripting manual.

I’m merging these into one modern, multi-page manual, built with MkDocs+ Material theme.

  • Easier navigation
  • Consistent look and feel
  • All topics in one place

You can preview it here: Traintastic manual

I’d love your thoughts:

  • Is the navigation clear?
  • Does the layout make it easier to read?
  • What is missing in the “Getting Started” section?

Feedback and ideas are very welcome and if you spot areas you’d like to help expand, let me know!

2

I would like to help you with this.

3

That’s awesome :slight_smile:

I’ll need todo some clean-up and then I’ll push the work in progress version to GitHub. I’ll let you know when it is ready, I’d hope within a few days.

4

@PrinceofNaxos it took me a few more days due to other priorities :slight_smile:

All code is pushed to GitHub, it is all on the master branch. The manual can be build by running the build.py script in the manual directory. If not yet installed, the Python packages listed in requirments.txt need to be installed in order to build the manual.

The build.py script will generate first a mkdocs.yml and the markdown files for the Lua scripting reference, then is calls MkDocs to build the manual.

The Traintastic client application now has a –-screenshot option, this can be used to generate/update screenshots used in the manual. The logic is in C++ code, for new images adding a manually created screenshots is fine. They can be added to this option later.

Please let me know if there is something unclear, happy to help :slight_smile: