-
-
Notifications
You must be signed in to change notification settings - Fork 3
Open
Labels
Description
Description
Currently, Speech Analyzer documentation is contained in a collection of Markdown files located in the help folder. The documentation is manually built on a developer's machine using pandoc and Windows HTML Workshop software to generate a CHM (compiled HTML help) file that runs on Windows. The CHM is checked into the repo and then included in the installer when the installer is built.
We'd like to change this process so that:
- help documentation is built on GHA CI instead of a developer machine
- we no longer have generated CHM, PDF or HTML help files checked into our repo. Only the source MD files are necessary
- we can potentially engage a non-programmer to help update the help docs
- we deploy a public static website containing our help documentation using GitHub Pages https://sillsdev.github.io/speechanalyzer
Some initial thoughts
- Pandoc is the software used to convert the Markdown source into CHM, PDF and HTML formats for distribution. Our current use of Pandoc to compile to CHM requires a Windows environment. While Pandoc itself is cross-platform, we will need a Windows CI environment in order to actually build the CHM. Pandoc provides Docker images based on Alpine. I don't know if it will be helpful to use these or not in our build process.
- In order to deploy to GitHub Pages, we can make use of a new GH Pages beta feature to deploy a static site via GHA.
- We should have a separate GHA workflow that triggers on release that also builds our help files (for inclusion in the installer) and deploys the help docs to our static site.