Build and publish manual with mdBook

[alexdewar]

This PR adds some skeleton files for the documentation and adds a CI workflow to build them with mdBook and publish to GitHub Pages. I've tested it by manually running the workflow. You can see the results here: https://energysystemsmodellinglab.github.io/MUSE_2.0/

The API documentation is still being published to GitHub Pages too; it's accessible via a link on the main page.

Closes #36.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 81.81%. Comparing base (e237e28) to head (0232e77).

❗ Current head 0232e77 differs from pull request most recent head 76fcbad

Please upload reports for the commit 76fcbad to get more accurate results.

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #47   +/-   ##
=======================================
  Coverage   81.81%   81.81%           
=======================================
  Files           7        7           
  Lines          77       77           
=======================================
  Hits           63       63           
  Misses         14       14           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[dalonsoa]

I've a couple of questions, but otherwise it looks OK!

[dalonsoa]

This should not be needed if book is gitignored, as it is, now.

[dalonsoa]

Is there anything in api just after running mdbook build?

[alexdewar]

Yep. There's the readme file I put in docs/api. But you're right that that should probably just
be replaced with a .gitkeep file.

[alexdewar]

Actually, there is the muse2 folder (containing only a .gitkeep file), so we do still need to clean the folder out otherwise we get an error because muse2/ already exists.

[dalonsoa]

Is there no such a thing as doc dependencies or dev dependencies in rust? If so, this dependency should go in that section and here just install those, so the same setup can be used when building the documentation locally.

[alexdewar]

Good point! Seemingly there's no such thing as doc dependencies in cargo, but there is dev
dependencies, so I'll add mdBook there.

[alexdewar]

I've had a look and this sadly doesn't seem possible currently 😞. I think this is the relevant upstream issue: rust-lang/cargo#9096

The problem is that cargo won't let you have an executable as a dependency. You can add mdbook as a dep, but when it installs you don't get the mdbook binary.

[dalonsoa]

What do you need this placeholder for? If it is just for keeping the directory structure, you can add a .gitkeep file. See https://stackoverflow.com/a/7229996/3778792

[alexdewar]

Yeah, kind of. It's because we link to it from a markdown folder in docs/, so if the folder doesn't exist then the markdown link checker complains. But a .gitkeep file is a better idea.