Documentation in HTML format

[stfnp]

The user manual is currently a PDF file created with LaTex. Having the documentation in HTML would have several advantages:

• Better integration into the website
• Better visibility for search engines
• Not bound to A4 pages
• Easier navigation

There are lots of tools/formats for generating HTML documentation, some of them are

• Sphinx
• mdBook
• MkDocs
• AsciiDoc
  • Example:
    • HTML: https://fxdocs.github.io/docs/html5/
    • PDF: https://fxdocs.github.io/docs/pdf/index.pdf
  • Extension for multipage output
  • Extension for maths in pdf output
• Quarto
• Docusaurus
• DocBook

Requirements

• Must work offline
• Can export a PDF as well
• Support for mathematical equations
• Bonus points if the theory manual could be converted too

Notes while testing some of them:

• mdBook

  • PDF export is not great
  • Does not allow for empty "summary chapters"

• Asciidoctor

  • Best one so far. Much more powerful than Markdown, but still easy to write.
  • Produces acceptable PDFs with some tweaking
  • Only single page HTML out of the box, but there is an extension

[stfnp]

Asciidoctor version, to be completed and merged here: https://github.com/stfnp/virtualbow-user-manual