Documentation pipelines

HeartAI documentation hosted on this website implements a semi-automated development and deployment pipeline. Current support exists for the following approaches:

  • Direct documentation development and modification.
  • Documentation pipeline with Markdown.
  • Documentation pipeline with Overleaf.

Prerequisites

HeartAI GitHub repository

The documentation pipelines require the HeartAI GitHub repository to be present on a developer’s system. Please coordinate with HeartAI administrators for access to the HeartAI repository.

This repository will appear as a 404 page-not-found if the developer does not have access to the HeartAI GitHub repository.

In addition, for the documentation pipeline approaches (those approaches supporting local website builds), the following software is required:

The documentation pipeline approaches also require the HeartAI repository to be present on the developer’s local machine or appropriate remote machine. Please refer to the documentation section Development: Deploying to a development environment for more information.

Direct documentation development and modification

Mastering Markdown

HeartAI documentation is primarily developed with Markdown. Further information about Markdown may be found with the following guide:

Documentation may be developed and modified directly by making changes to the HeartAI GitHub repository. The corresponding location for HeartAI documentation may be found here:

[HeartAI repository]/docs/src/main/paradox

Please feel welcome to modify documentation through addition or edit.

The following example shows how to submit a documentation modification for review:

heartai-direct-documentation-development-and-modification.png

Documentation pipeline: Markdown

Mastering Markdown

HeartAI documentation is primarily developed with Markdown. Further information about Markdown may be found with the following guide:

MathJax integration

Markdown documents may be integrated with MathJax to allow rendering of LaTeX mathematical typesetting. This is achievable by including the following JavaScript script to a corresponding Markdown document:

<script type="text/x-mathjax-config">
  MathJax.Hub.Config({tex2jax: {inlineMath: [['$','$'], ['\\(','\\)']]}});
</script>
<script type="text/javascript"
  src="http://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>

Developers may create documentation with Markdown. This approach is best suited for documents that don’t require real-time collaboration. Markdown documentation files may be found at the corresponding location in the HeartAI repository. The prefix directory location is:

[HeartAI repository]/docs/src/main/paradox
  • sbt and Paradox provide the functionality to build the HeartAI website. In the HeartAI repository root directory (the directory with the build.sbt file) the website may be built with the following command:
sbt docs/paradox
  • The website will now be available on the developer’s local environment at the following location:
[HeartAI repository]/docs/target/paradox/site/main/index.html
  • The developer should review the local website build, and when ready, push the updates to the HeartAI repository.

  • The developer may then create a pull request to the master branch.

  • HeartAI repository administrators will review the updated website build, and deploy this to the gh-pages branch of the repository. This will trigger the hosting of the website on GitHub Pages.

https://www.heartai.net

The following figure shows an overview of this approach:

HAI-Markdown-Documentation-Pipeline.svg

Documentation pipeline: Overleaf

For documentation that requires real-time collaboration or LaTeX integration, development with Overleaf is the preferred documentation pipeline.

Pandoc

In addition to the general prerequisites listed above, the Overleaf development pipeline requires Pandoc for converting the Overleaf LaTeX files to the Markdown format. The Pandoc software may be downloaded from the following location:

  • The developer may develop documentation with the Overleaf software. Please ask HeartAI administrators for access to the corresponding Overleaf projects.
  • If the developer has an Overleaf Pro account and if Dropbox has been installed, the source code for the Overleaf projects will be sychronised automatically to the users local filesystem. Otherwise, the source code may be manually exported.
  • Pandoc allows the conversion of LaTeX format documentation to Markdown format documentation. With Bash, the following command will perform the conversion:
pandoc -s -f latex -t markdown-citations [INPUT.tex] -o [OUTPUT.md] --bibliography [REFERENCES.bib] --csl=[CSL.csl]
  • MathJax provides rendering of LaTeX format mathematics. The developer may manually insert the required script or may develop an automated approach:
<script type="text/x-mathjax-config">
  MathJax.Hub.Config({tex2jax: {inlineMath: [['$','$'], ['\\(','\\)']]}});
</script>
<script type="text/javascript"
  src="http://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
  • The converted Markdown documentation files should be moved to the corresponding location in the HeartAI directory. The prefix directory location is:
[HeartAI repository]/docs/src/main/paradox
  • An additional Markdown file should be created in the same directory to serve as the documentation index. This index must itself have a parent index, continuing towards the root index. These indexes must be present for the following steps to succeed. Please refer to the following documentation:

https://developer.lightbend.com/docs/paradox/current/directives/organizing-pages.html

  • sbt and Paradox provide the functionality to build the HeartAI website. In the HeartAI repository root directory (the directory with the build.sbt file) the website may be built with the following command:
sbt docs/paradox
  • The website will now be available on the developer’s local environment at the following location:
[HeartAI repository]/docs/target/paradox/site/main/index.html
  • The developer should review the local website build, and when ready, push the updates to the HeartAI repository.

  • The developer may then create a pull request to the master branch.

  • HeartAI repository administrators will review the updated website build, and deploy this to the gh-pages branch of the repository. This will trigger the hosting of the website on GitHub Pages.

https://www.heartai.net

The following figure shows an overview of this approach:

HAI-Overleaf-Documentation-Pipeline.svg

Documentation review and publication process

The HeartAI team are committed to transparent and shared development for the betterment of the health system and health community. This includes the appropriate public release of information relating to HeartAI and associated projects. To ensure that information released to the public is not of a sensitive or confidential nature, the HeartAI documentation process has an integrated and enforced review and remediation policy:

documentation-review-and-publication-process.svg

Publishing the HeartAI website to GitHub Pages

  • In the HeartAI project root directory:
[[email protected] HeartAI]$ origin=$(git remote get-url origin)
  • In the HeartAI compiled website directory:
[[email protected] HeartAI/docs/target/paradox/site/main]$ git add .
[[email protected] HeartAI/docs/target/paradox/site/main]$ git commit -m "Update gh-pages"
[[email protected] HeartAI/docs/target/paradox/site/main]$ git push "$origin" master:gh-pages
Administrator privileges required

The developer is required to have administrator privileges to publish to the gh-pages branch.