Skip to content
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.

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

feat: automatically build and deploy our documentation #98

Open
megahirt opened this issue Jan 19, 2023 · 0 comments
Open

feat: automatically build and deploy our documentation #98

megahirt opened this issue Jan 19, 2023 · 0 comments

Comments

@megahirt
Copy link
Contributor

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants