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

[tomcl]

Thanks This is really great. I am very thankful to be getting rid of jekyll! Feedback on it will however need to await when I have decent dev time and can do a merge and look at everything (I need to do this because otherwise I will not understand it!).

[tomcl]

Just looked at your demo
https://timothycdc.github.io/issie/

This is great. The top-level advert and carousel has not been moved across - I guess it is a whole load of JS. Since that top-level page is not great I think losing it is not a problem - although there should arguably be a replacement.

• How is the order of the pages within each section decided? I notice currently it is not uniformly alphabetic.
• Can these pages be themed? How?

I guess answers to both are in the fsdocs documentation...

fsdocs is much cleaner to use and maintain than Jekyll!

[timothycdc]

Hi Professor, glad you liked the changes.

I will take a look at a replacement for the top-level advert and carousel when I have time.

The order of pages are decided in the frontmatter.

Pages can be themed either through CSS or HTML templates.