New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation in HTML format #214

Closed

stfnp opened this issue Sep 26, 2021 · 1 comment

Labels

area: documentation type: improvement

Milestone

Contributor

stfnp commented Sep 26, 2021 •

edited

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 added area: documentation type: improvement labels

stfnp added this to the Version 0.9 milestone

Contributor Author

stfnp commented Apr 2, 2022

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

stfnp closed this as completed in

7312ed5

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment