microsoft/openvmm
Publicmirrored from https://github.com/microsoft/openvmmAvailable
Guide/src/dev_guide/contrib/guide.md
88lines · modecode
| 1 | # Updating this Guide |
| 2 | |
| 3 | We gladly welcome PRs that improve the quality of the OpenVMM guide! |
| 4 | |
| 5 | The OpenVMM Guide is written in Markdown, and rendered to HTML using |
| 6 | [mdbook](https://github.com/rust-lang/mdBook). You can find the source-code of |
| 7 | this Guide in the main OpenVMM GitHub repo, in the |
| 8 | [`Guide/`](https://github.com/microsoft/openvmm/tree/main/Guide) folder. |
| 9 | |
| 10 | ## Editing the Guide |
| 11 | |
| 12 | ### Small Changes |
| 13 | |
| 14 | For small changes, you can simply click the "Suggest an Edit" button in the |
| 15 | top-right corner of any page to automatically open up a GitHub Edit page. |
| 16 | |
| 17 | ### Medium Changes |
| 18 | |
| 19 | For medium changes, we suggest cloning the repo locally, and previewing changes |
| 20 | to Markdown in your editor (Visual Studio Code has good support for this). |
| 21 | |
| 22 | ### Large Changes |
| 23 | |
| 24 | For large changes, we suggest cloning the repo locally, and building a fully |
| 25 | rendered copy of the Guide using `mdbook`. |
| 26 | |
| 27 | This is very useful when making changes that leverage mdbook preprocessors, such |
| 28 | as using mermaid diagrams, or previewing admonishments. |
| 29 | |
| 30 | ```admonish info |
| 31 | For example, the `mdbook-admonish` preprocessor is what powers this nice looking |
| 32 | "Info" box! |
| 33 | ``` |
| 34 | |
| 35 | Building the Guide locally is quite straightforward: |
| 36 | |
| 37 | 1. Install `mdbook` and the additional preprocessors we use locally: |
| 38 | |
| 39 | ```bash |
| 40 | cargo install mdbook |
| 41 | cargo install mdbook-admonish |
| 42 | cargo install mdbook-mermaid |
| 43 | ``` |
| 44 | |
| 45 | 2. Navigate into the `Guide/` directory, and run `mdbook`: |
| 46 | |
| 47 | ```bash |
| 48 | cd Guide/ |
| 49 | # must be run inside the `Guide/` directory! |
| 50 | mdbook serve |
| 51 | ``` |
| 52 | |
| 53 | 3. Navigate to the localhost URL in your web browser (typically |
| 54 | `http://127.0.0.1:3000/`) |
| 55 | |
| 56 | ### Troubleshooting |
| 57 | |
| 58 | #### Running `mdbook serve` outside the `Guide/` directory |
| 59 | |
| 60 | **Error:** |
| 61 | |
| 62 | ``` |
| 63 | 2024-10-29 16:26:22 [INFO] (mdbook::book): Book building has started |
| 64 | error: manifest path `./mdbook-openvmm-shim/Cargo.toml` does not exist |
| 65 | ``` |
| 66 | |
| 67 | **Solution:** |
| 68 | |
| 69 | Ensure you have changed your working-directory to the `Guide/` folder (e.g: via |
| 70 | `cd Guide/`), and then run `mdbook serve`. |
| 71 | |
| 72 | #### Rust is not installed |
| 73 | |
| 74 | **Error:** |
| 75 | |
| 76 | ``` |
| 77 | 2024-10-29 16:35:49 [INFO] (mdbook::book): Book building has started |
| 78 | 2024-10-29 16:35:49 [WARN] (mdbook::preprocess::cmd): The command wasn't found, is the "admonish" preprocessor installed? |
| 79 | 2024-10-29 16:35:49 [WARN] (mdbook::preprocess::cmd): Command: cargo run --quiet --manifest-path ./mdbook-openvmm-shim/Cargo.toml mdbook-admonish |
| 80 | ``` |
| 81 | |
| 82 | **Solution:** |
| 83 | |
| 84 | The OpenVMM Guide hooks into a custom Rust utility called `mdbook-openvmm-shim`, |
| 85 | which must be compiled in order for `mdbook` to successfully build the OpenVMM |
| 86 | guide. |
| 87 | |
| 88 | Please ensure you have [installed Rust](../getting_started/linux.md#installing-rust). |
| 89 | |