Move doc generation to mkdocs.

The generated "content" (ie, .html layout, #refs etc) is the same as
generated by mdbook - all old links should be unchanged.

The other theme etc generated stuff is obviously very different;
mkdocs using the 'material' theme.

.circleci/config.yml

@@ -3,19 +3,17 @@
 version: 2.1
 
 commands:
-  install-mdbook:
+  install-mkdocs:
     steps:
       - run:
           name: Install mdBook
           command: |
-            mkdir -p $HOME/.bin
-            pushd $HOME/.bin
-            # mdbook
-            curl -sfSL --retry 5 --retry-delay 10 https://github.com/rust-lang-nursery/mdBook/releases/download/v0.4.35/mdbook-v0.4.35-x86_64-unknown-linux-gnu.tar.gz | tar xz
-            # mdbook-link-check
-            curl -sfSL --retry 5 --retry-delay 10 https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/download/v0.7.7/mdbook-linkcheck.x86_64-unknown-linux-gnu.zip -o mdbook-linkcheck.zip && unzip mdbook-linkcheck.zip && chmod +x mdbook-linkcheck
-            echo 'export PATH="$HOME/.bin:$PATH"' >> $BASH_ENV
-            popd
+            sudo apt-get update -qq
+            sudo apt-get install -qy --no-install-recommends python3-pip
+            sudo apt-get clean
+            pip install mkdocs
+            pip install mkdocs-material
+
   # Our policy for updating rust versions is at https://github.com/mozilla/uniffi-rs/tree/main/docs/policies/rust-versions.md
   # See also rust-toolchain.toml in the root of this repo, which is used to specify our official target version.
   prepare-rust-target-version:
@@ -127,10 +125,10 @@ jobs:
       - prepare-rust-target-version
       - build-api-docs
       - run: cp -r ./target/doc ./docs/manual/src/internals/api
-      - install-mdbook
-      - run: mdbook build docs/manual
+      - install-mkdocs
+      - run: python -m mkdocs build
       - gh-pages/deploy:
-          build-dir: docs/manual/book/html
+          build-dir: target/rendered-docs
           ssh-fingerprints: "ac:68:a3:78:ea:ee:00:05:30:e1:dc:1f:2e:2f:7c:81"
 
   Deploy Docker:

.gitignore

@@ -5,5 +5,8 @@ target
 .idea
 xcuserdata
 docs/manual/src/internals/api
+# The old mdbook outdir
+docs/manual/book
+
 examples/app/ios/Generated
 examples/app/ios/IOSApp.xcodeproj/project.xcworkspace/xcshareddata/

docs/manual/src/foreign_traits.md

@@ -21,7 +21,7 @@ a [compatible error type](./udl/errors.md) - see below for more on error handlin
 
 For example:
 
-```rust,no_run
+```rust
 pub trait Keychain: Send + Sync + Debug {
   fn get(&self, key: String) -> Result<Option<String>, KeyChainError>;
   fn put(&self, key: String, value: String) -> Result<(), KeyChainError>;
@@ -57,7 +57,7 @@ interface Authenticator {
 
 In Rust we'd write:
 
-```rust,no_run
+```rust
 struct Authenticator {
   keychain: Arc<dyn Keychain>,
 }

docs/manual/src/tutorial/foreign_language_bindings.md

@@ -1,6 +1,6 @@
 # Foreign-language bindings
 
-As stated in the [Overview](../Overview.md), this library and tutorial does not cover *how* to ship a Rust library on mobile, but how to generate bindings for it, so this section will only cover that.
+This describes how to generate foreign bindings.
 
 ## Creating the bindgen binary
 

docs/manual/src/udl/structs.md

@@ -6,7 +6,7 @@ Think of them like a Rust struct without any methods.
 
 A Rust struct like this:
 
-```rust,no_run
+```rust
 struct TodoEntry {
     done: bool,
     due_date: u64,
@@ -50,7 +50,7 @@ dictionary TodoEntry {
 
 Then the corresponding Rust code would need to look like this:
 
-```rust,no_run
+```rust
 struct TodoEntry {
     owner: std::sync::Arc<User>,
     text: String,
@@ -102,7 +102,7 @@ dictionary TodoEntry {
 
 The corresponding Rust struct would need to look like this:
 
-```rust,no_run
+```rust
 struct TodoEntry {
     done: bool,
     text: Option<String>,

mkdocs.yml

@@ -0,0 +1,74 @@
+# mkdocs:
+# Prepare: pip install mkdocs; mkdocs-material
+# Testing: python -m mkdocs serve
+# Build into ./target/rendered-docs: python -m mkdocs build
+# In CI, `cargo doc` output will have been copied to some deep 'api/' directory, you may see warnings for that.
+# We should see if we can move that process into here via an extension?
+
+site_name: The UniFFI user guide
+docs_dir: docs/manual/src
+site_dir:  'target/rendered-docs'
+repo_url: 'https://github.com/mozilla/uniffi-rs'
+use_directory_urls: false
+
+theme:
+  name: 'material'
+  language: 'en'
+
+# XXX - not getting highlighting in, eg, ```rust``` blocks???
+# tried this :(
+# markdown_extensions:
+#  - codehilite
+
+# This lists all the files that become part of the documentation
+nav:
+- ./Motivation.md
+- 'Tutorial':
+  - ./Getting_started.md
+  - ./tutorial/Prerequisites.md
+  - ./tutorial/udl_file.md
+  - ./tutorial/Rust_scaffolding.md
+  - ./tutorial/foreign_language_bindings.md
+- 'The UDL file':
+  - ./udl_file_spec.md
+  - ./udl/namespace.md
+  - ./udl/builtin_types.md
+  -  ./udl/enumerations.md
+  -  ./udl/structs.md
+  - 'Functions':
+    - ./udl/functions.md
+    - ./udl/errors.md
+  - 'Interfaces and Objects':
+    - ./udl/interfaces.md
+    - ./udl/callback_interfaces.md
+  - 'External Types':
+    - ./udl/ext_types.md
+    - ./udl/ext_types_external.md
+    - ./udl/custom_types.md
+  - ./udl/docstrings.md
+- ./proc_macro/index.md
+- ./futures.md
+
+- 'Bindings':
+  - ./bindings.md
+  - ./foreign_traits.md
+
+  - 'Kotlin':
+    - ./kotlin/configuration.md
+    - ./kotlin/gradle.md
+    - ./kotlin/lifetimes.md
+
+  - 'Swift':
+    - ./swift/overview.md
+    - ./swift/configuration.md
+    - ./swift/module.md
+    - ./swift/xcode.md
+
+  - 'Python': ./python/configuration.md
+
+- Internals:
+  - ./internals/design_principles.md
+  - ./internals/crates.md
+  - ./internals/lifting_and_lowering.md
+  - ./internals/object_references.md
+  - ./internals/rendering_foreign_bindings.md