Updating the documentation

Introduction

The ISSIE documentation is generated by fsdocs from Markdown documents by the GitHub action .github/workflows/docs.yml, which runs build_docs.sh on every push to master. That outputs a static website to the gh-pages branch, and changes to that branch are automatically deployed to the documentation website.

To change the documentation PR the markdown files to ISSIE master, rebuilding will be automatic when the changes are committed to master.

The Markdown source files can be found on the ISSIE repo:

• Documentation Pages: /docs/*.md
• ISSIE Blog Pages: /docs/updates/*.md
• Embedded (PNG) graphics: /docs/img/**/*.md
• In documentation source files the file path separator is always /

How to develop documentation

For developer preview of changes use dotnet fsdocs watch --noapidocs in the repo root directory. The documentation (without API) will be generated and a browser window opened to preview. Changes will get reloaded automatically.

See Issue 532 for more details of why watch does not work with API.

PR to ISSIE master the changed documentation.

Gotcha

build_docs.sh refuses to finish if fsdocs produced no output/index.html. That check is there because fsdocs catches its own phase errors and still exits 0, and the deploy step publishes whatever is in output/ — so without it a failed build silently replaced the live site while the workflow stayed green. If the docs job fails at that line, read the fsdocs output above it rather than re-running.

No secret needs managing: .github/workflows/docs.yml authenticates with secrets.GITHUB_TOKEN, which GitHub mints for each run. (An earlier version of this page described a deploy key that had to be regenerated every six months. There is no such key now.)