docs: Add Makefile generation target and CI testing

[Zildj1an]

Add Makefile target to generate cargo documentation and update README accordingly.

[00xc]

Would it make sense to add the documentation build process to Github CI? We can make the build fail on warnings with:

RUSTDOCFLAGS="-D warnings" cargo doc --all-features --document-private-items

[Zildj1an]

Would it make sense to add the documentation build process to Github CI? We can make the build fail on warnings with:

RUSTDOCFLAGS="-D warnings" cargo doc --all-features --document-private-items

Yes, that would be very positive, agreed.

[Zildj1an]

I have combined the PR #132 with this one and added --all-features. Thanks @00xc

[stefano-garzarella]

IIUC from https://doc.rust-lang.org/cargo/commands/cargo-doc.html, we will not generate the svsm binary documentation, since we also have the svsm library:

The binary will be skipped if its name is the same as the lib target.

Indeed, using --bins will show only the binary docs.
I don't know if there is a solution to have both, but I think for now it is okay to generate only the library documentation.

[00xc]

We still need to fail, at least in CI, if there are warnings in the build. This can be done in the Makefile:

diff --git a/Makefile b/Makefile
index 8725dcf..6beaf91 100644
--- a/Makefile
+++ b/Makefile
@@ -20,7 +20,7 @@ test:
        cargo test --target=x86_64-unknown-linux-gnu
 
 doc:
-       cargo doc --open --all-features --document-private-items
+       RUSTDOCFLAGS="-D warnings" cargo doc --open --all-features --document-private-items
 
 utils/gen_meta: utils/gen_meta.c
        cc -O3 -Wall -o $@ $<

Or in Github Actions:

diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml
index ca67d19..04121e9 100644
--- a/.github/workflows/rust.yml
+++ b/.github/workflows/rust.yml
@@ -57,3 +57,5 @@ jobs:
 
       - name: Check documentation
         run: make doc
+        env:
+          RUSTDOCFLAGS: -D warnings

Not sure which one is the best approach.

[Zildj1an]

Thanks @00xc I have updated setting RUSTDOCFLAGS in the workflow and rebased. But we got:

error: unresolved link to `pages`
  --> src/mm/vm/mapping/rawalloc.rs:23:39
   |
23 |     /// Number of pages required in [`pages`]
   |                                       ^^^^^ no item named `pages` in scope
   |
   = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
   = note: `-D rustdoc::broken-intra-doc-links` implied by `-D warnings`

error: could not document `svsm`

which makes me think we actually don't want to fail on warnings, right?

[00xc]

Thanks @00xc I have updated setting RUSTDOCFLAGS in the workflow and rebased. But we got:
...
which makes me think we actually don't want to fail on warnings, right?

I would want them, it's just a matter of fixing remaining warnings before merging this.

[osteffenrh]

Looks good.
Remember to merge #124 first :-)

[Zildj1an]

Thanks @00xc I have updated setting RUSTDOCFLAGS in the workflow and rebased. But we got:
...
which makes me think we actually don't want to fail on warnings, right?

I would want them, it's just a matter of fixing remaining warnings before merging this.

@00xc but I don't think that this warning is generated by this PR?

error: unresolved link to `pages`
  --> src/mm/vm/mapping/rawalloc.rs:23:39
   |
23 |     /// Number of pages required in [`pages`]
   |                                       ^^^^^ no item named `pages` in scope
   |
   = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
   = note: `-D rustdoc::broken-intra-doc-links` implied by `-D warnings`

error: could not document `svsm`

[00xc]

@00xc but I don't think that this warning is generated by this PR?

error: unresolved link to `pages`
  --> src/mm/vm/mapping/rawalloc.rs:23:39
   |
23 |     /// Number of pages required in [`pages`]
   |                                       ^^^^^ no item named `pages` in scope
   |
   = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
   = note: `-D rustdoc::broken-intra-doc-links` implied by `-D warnings`

error: could not document `svsm`

No, it was introduced before. It should be fixed by #144.

[00xc]

LGTM. Once the PR mentioned above is merged CI should no longer fail.