Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Build and publish manual with mdBook #47

Merged
merged 4 commits into from
Jun 6, 2024
Merged

Build and publish manual with mdBook #47

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e72122e
Add mdBook skeleton
alexdewar May 29, 2024
d6d7f6e
Build and publish mdBook docs
alexdewar Jun 5, 2024
d250ff7
Remove unnecessary rm in workflow
alexdewar Jun 6, 2024
76fcbad
Replace pointless readme file with .gitkeep
alexdewar Jun 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 13 additions & 5 deletions .github/workflows/docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,22 @@ jobs:
uses: dtolnay/rust-toolchain@stable
- name: Setup pages
uses: actions/configure-pages@v5
- name: Build docs
run: cargo doc --no-deps
- name: Add redirect
run: echo '<meta http-equiv="refresh" content="0;url=muse2/index.html">' > target/doc/index.html
- name: Install mdBook
run: cargo install mdbook
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

- name: Build docs with mdBook
run: |
mdbook build
- name: Build API docs
run: |
cargo doc --no-deps

# Put API documentation in with book
rm -r book/api/*
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there anything in api just after running mdbook build?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

mv target/doc/* book/api
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: target/doc
path: book
deploy:
name: Deploy
environment:
Expand Down
4 changes: 4 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,7 @@ Cargo.lock

# MSVC Windows builds of rustc generate these, which store debugging information
*.pdb

# mdBook output
book/
index.html
6 changes: 6 additions & 0 deletions book.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
[book]
authors = ["Alex Dewar"]
language = "en"
multilingual = false
src = "docs"
title = "MUSE 2.0"
5 changes: 5 additions & 0 deletions docs/SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Summary

[Introduction](./introduction.md)

- [Chapter 1](./chapter_1.md)
Empty file added docs/api/muse2/.gitkeep
View file
Open in desktop
Empty file.
3 changes: 3 additions & 0 deletions docs/chapter_1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Chapter 1

[Insert content here.]
9 changes: 9 additions & 0 deletions docs/introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# Introduction

MUSE 2.0 is a tool for running simulations of energy systems, written in Rust. It is a slimmer and
faster version of [the older MUSE tool].

The [API docs are available here].

[the older MUSE tool]: https://github.com/EnergySystemsModellingLab/MUSE_OS
[API docs are available here]: ./api/muse2