Revamp documentation

[timothycdc]

Demo

See a demo on my branch here.

Info

Previously, the repo relied on Jekyll to build a blog that provides a general description of Issie and the project. The blog however has gotten outdated over time and is rarely used, as it is seemingly more convenient to put information as standard markdown files within the repo.

Even further in the past, the Jekyll site also had API documentation for the functions within Issie, however functionality for this was removed at some point, and the scant documentation is out of date with the whole codebase.

This PR feature seeks to solve both problems by combining both API documentation and release/blog updates through a unified statically generated site powered by fsdocs. The F# compiler already can generate XML docs from XML comments, however fsdocs can convert this XML file (albeit with some hacking) into a neat website. The API docs are automatically updated with the master branch and the blog posts are displayed more cleanly.

Another bonus is that there is support for searching the docs, and it decently allows developers to find helpers more easily.

The build script ./build_docs.sh is called by the GitHub Workflow in /.github to push to GitHub Pages. It can also be called in the terminal build the docs locally for quick reference, hosting them on http://localhost:8901, but the project must be compilable to do so.

This PR will still require modification when deploying from the master branch, and a personal access token stored as ISSIE_DOCS_TOKEN under repository secrets. The token must have 'repo' scope.

./github/workflows/ci.yml:

on:
  push:
    branches:
      - tdc21_documentation # change to master 

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
    - name: Setup .NET Core
      uses: actions/setup-dotnet@v3
    - name: Restore tools
      run: dotnet tool restore
    - name: Paket install
      run: dotnet paket install
    - name: Run build_docs.sh
      run: ./build_docs.sh
    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.ISSIE_DOCS_TOKEN }}
        publish_dir: ./output


# A new personal access token must be generated to allow the GitHub Actions workflow to push to the repository.
# The token must have the 'repo' scope.
# Generate here https://github.com/settings/tokens/new
# Add the token to the repository secrets as ISSIE_DOCS_TOKEN
# https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository

Screenshots