Updating the documentation

Introduction

The ISSIE documentation is generated by fsdocs from Markdown documents using a Github action build .github/workflows/ci.yml. This action outputs a static website as generated by fsdocs to the root directory on the gh-pages branch of the repo. Changes to this 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

Documentation builds for ISSIE need a secret key on the repo generated as documented on the wiki.

This must be regenerated every 6 months or so and uploaded to the repo.