EnergySystemsModellingLab / EnergySystemsModellingLab/MUSE2

`mdbook serve` clobbers old versions of docs

Open Beginner friendly
#1,367 1 comment 0 reactions 0 assignees View on GitHub
bug documentation
Dominant language
Rust
Stars
8
Forks
5
Avg merge
1d 2m
Merged PRs (30d)
37

Description

Not an especially important bug.

I often run `mdbook serve -o` to view the documentation once I've built it, but if you build the old docs (`just build_docs::all_with_old`) then run `mdbook`, the old docs are deleted again. The problem is that we have a folder at `docs/release` which just contains some Python code, but `release` is also the name of the folder where we put old versions of docs when we generate them. When you run `mdbook serve` it clobbers the contents of `book/release` with `docs/release`.

You can just open `book/index.html` directly instead. We could fix this by renaming `docs/release` to something else.

Contributor guide

Open the contributing guide

Research direction

Start by inspecting docs/release and the build_docs::all_with_old recipe in just, then reproduce the conflict with mdbook serve -o. Identify references that depend on the docs/release path and choose a non-conflicting name. Done means building old documentation and running mdbook serve no longer removes book/release or its contents.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
build-system, documentation
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
65/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.