Publish rune docs to netlify

I tried different things and ended up choosing netlify. Netlify has a
very powerful build system and it's running on Ubuntu, but it did not
allow for apt-get installs. Since we need pango and gdk to run `cargo
doc` on the crate, moved to Github actions.

As part of the same PR, I fixed all the warnings on cargo doc, making
sure that the documentation is correctly published. The trick to deploy
cargo doc is to deploy `target/doc` and then pair that with a redirect
of the main page (configured rune-rs.netlify.app on my own account) to
`/rune` which (as the main crate) has the info about the subcrates as well.

Closes CeleritasCelery#48

.github/workflows/publish-docs.yml

@@ -0,0 +1,37 @@
+name: build and deploy to netlify
+on:
+  push:
+    branches: [master]
+jobs:
+  publish-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+      - name: Install the required system libraries
+        run: sudo apt-get -y install libpango1.0-dev libgtk-3-dev
+      # run docs generation on nightly rather than stable. This enables features like
+      # https://doc.rust-lang.org/beta/unstable-book/language-features/doc-cfg.html which allows an
+      # API be documented as only available in some specific platforms.
+      - name: Install nightly
+        uses: dtolnay/rust-toolchain@nightly
+      - name: cargo doc
+        run: cargo +nightly doc --no-deps --all-features --workspace
+        env:
+          RUSTDOCFLAGS: -D warnings
+      - name: Deploy to Netlify
+        uses: nwtgck/actions-netlify@v2.0
+        with:
+          publish-dir: "./target/doc"
+          production-branch: master
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          deploy-message: "Deploy from GitHub Actions"
+          enable-pull-request-comment: false
+          enable-commit-comment: true
+          overwrites-pull-request-comment: true
+          netlify-config-path: "./netlify.toml"
+        env:
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+        timeout-minutes: 1

netlify.toml

@@ -0,0 +1,3 @@
+[[redirects]]
+  from = "/"
+  to = "/rune"

src/buffer.rs

@@ -17,7 +17,7 @@ static BUFFERS: OnceLock<Mutex<HashMap<String, &'static LispBuffer>>> = OnceLock
 
 /// Helper function to avoid calling `get_or_init` on each of the calls to `lock()` on the Mutex.
 ///
-/// TODO: Use `LazyLock`: https://github.com/CeleritasCelery/rune/issues/34
+/// TODO: Use `LazyLock`: <https://github.com/CeleritasCelery/rune/issues/34>
 fn buffers() -> &'static Mutex<HashMap<String, &'static LispBuffer>> {
     BUFFERS.get_or_init(Mutex::default)
 }

src/core/env/symbol.rs

@@ -17,7 +17,8 @@ use std::sync::atomic::{AtomicBool, AtomicPtr, Ordering};
 /// will be the same location no matter which thread
 /// interned it. Functions are safe to share between
 /// threads because they are marked immutable by
-/// [`ObjectMap::set_func`] and they can only be replaced atomically.
+/// [`ObjectMap::set_func`](`crate::core::env::ObjectMap::set_func`)
+/// and they can only be replaced atomically.
 /// In order to garbage collect the function we need to
 /// halt all running threads. This has not been implemented
 /// yet.

src/core/object/cell.rs

@@ -44,7 +44,7 @@ impl fmt::Debug for ObjCell {
 
 /// This represents a mutable view into an Object. See [`ObjCell`] for a more
 /// detailed explanation. Holding this type means that we confirmed that the
-/// data stucture is mutable, and we can use the [`set`] method update this
+/// data stucture is mutable, and we can use the [`MutObjCell::set`] method update this
 /// cell.
 #[derive(PartialEq)]
 #[repr(transparent)]

src/core/object/tagged.rs

@@ -178,7 +178,7 @@ impl<'new, 'old, T: GcManaged + 'new> WithLifetime<'new> for &'old T {
 
 /// Trait for types that can be managed by the GC. This trait is implemented for
 /// as many types as possible, even for types that are already Gc managed, Like
-/// Gc<T>. This makes it easier to write generic code for working with Gc types.
+/// `Gc<T>`. This makes it easier to write generic code for working with Gc types.
 pub(crate) trait IntoObject {
     type Out<'ob>;
 
@@ -365,7 +365,7 @@ mod private {
     /// of types that implement this trait. First is "base" types, which are
     /// pointers to some memory managed by the GC with a unique tag (e.g
     /// `LispString`, `LispVec`). This may seem stange that we would define a
-    /// tagged pointer when the type is known (i.e. Gc<i64>), but doing so let's
+    /// tagged pointer when the type is known (i.e. `Gc<i64>`), but doing so let's
     /// us reinterpret bits without changing the underlying memory. Base types
     /// are untagged into a pointer.
     ///
@@ -400,7 +400,7 @@ mod private {
             Gc::from_ptr(ptr, Self::TAG)
         }
 
-        /// Remove the tag from the Gc<T> and return the inner type. If it is
+        /// Remove the tag from the `Gc<T>` and return the inner type. If it is
         /// base type then it will only have a single possible value and can be
         /// untagged without checks, but sum types need to create all values
         /// they can hold. We use tagged base types to let us reinterpret bits

src/core/object/vector.rs

@@ -13,7 +13,7 @@ use std::{
 
 /// A lisp vector. Unlike vectors in other languages this is not resizeable.
 /// This type is represented as slice of [`ObjCell`] which is immutable by
-/// default. However with the [`try_mut`] method, you can obtain a mutable view
+/// default. However with the [`LispVec::try_mut`] method, you can obtain a mutable view
 /// into this slice.
 #[derive(Eq)]
 pub(crate) struct LispVec {

src/data.rs

@@ -14,11 +14,11 @@ use std::sync::OnceLock;
 static FEATURES: OnceLock<Mutex<HashSet<Symbol<'static>>>> = OnceLock::new();
 
 /// Rust translation of the `features` variable: A list of symbols are the features
-/// of the executing Emacs. Used by [`featurep`] and [`require`], altered by [`provide`].
-/// Vended through a helper function to avoid calling `get_or_init` on each of the calls
+/// of the executing Emacs. Used by [`featurep`](`crate::fns::featurep`) and [`require`](`crate::fns::require`),
+/// altered by [`provide`]. Vended through a helper function to avoid calling `get_or_init` on each of the calls
 /// to `lock()` on the Mutex.
 ///
-/// TODO: Use `LazyLock`: https://github.com/CeleritasCelery/rune/issues/34
+/// TODO: Use `LazyLock`: <https://github.com/CeleritasCelery/rune/issues/34>
 pub(crate) fn features() -> &'static Mutex<HashSet<Symbol<'static>>> {
     FEATURES.get_or_init(Mutex::default)
 }

src/fns.rs

@@ -487,7 +487,7 @@ pub(crate) fn defvaralias<'ob>(
 pub(crate) fn featurep(_feature: Symbol, _subfeature: Option<Symbol>) {}
 
 #[defun]
-fn require<'ob>(
+pub(crate) fn require<'ob>(
     feature: &Rt<Gc<Symbol>>,
     filename: Option<&Rt<Gc<&LispString>>>,
     noerror: Option<()>,