Merge pull request #51 from metaborg/graphs-in-docs

Graphs in docs
metaborg · Jun 4, 2024 · d6e9153 · d6e9153
2 parents 768aa42 + b37e138
commit d6e9153
Show file tree

Hide file tree

Showing 148 changed files with 303,017 additions and 32 deletions.
diff --git a/.gitignore b/.gitignore
@@ -2,7 +2,6 @@
 # will have compiled files and executables
 debug/
 target/
-doc/
 
 # Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
 # More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
@@ -18,4 +17,6 @@ Cargo.lock
 .idea/
 
 *.dot
-.direnv
+.direnv
+
+**/render-docs
diff --git a/Cargo.toml b/Cargo.toml
@@ -4,9 +4,11 @@ members = [
     "scopegraphs",
     "scopegraphs-macros",
     "scopegraphs-regular-expressions",
+    "scopegraphs-render-docs",
 ]
 default-members = [
     "scopegraphs",
     "scopegraphs-macros",
     "scopegraphs-regular-expressions",
+    "scopegraphs-render-docs",
 ]
diff --git a/flake.nix b/flake.nix
@@ -20,13 +20,71 @@
         };
       in {
         devShells.default = pkgs.mkShell rec {
-          rustToolchain = pkgs.rust-bin.stable.latest.default.override {
-            targets = [ "wasm32-unknown-unknown" ];
-            extensions = [ "rust-src" "rust-analyzer" ];
-          };
-          RUST_SRC_PATH = "${rustToolchain}/lib/rustlib/src/rust/library";
+          buildInputs = with pkgs; [
+            # necessary for building wgpu in 3rd party packages (in most cases)
+            libxkbcommon
+            wayland
+            xorg.libX11
+            xorg.libXcursor
+            xorg.libXrandr
+            xorg.libXi
+            alsa-lib
+            fontconfig
+            freetype
+            shaderc
+            directx-shader-compiler
+            pkg-config
+            cmake
+            mold # could use any linker, needed for rustix (but mold is fast)
 
-          buildInputs = with pkgs; [ trunk rustToolchain cargo-watch ];
+            libGL
+            vulkan-headers
+            vulkan-loader
+            vulkan-tools
+            vulkan-tools-lunarg
+            vulkan-extension-layer
+            vulkan-validation-layers # don't need them *strictly* but immensely helpful
+
+            cargo-nextest
+            cargo-fuzz
+            cargo-watch
+
+            # nice for developing wgpu itself
+            typos
+
+            # if you don't already have rust installed through other means,
+            # this shell.nix can do that for you with this below
+            yq # for tomlq below
+            rustup
+
+            # nice tools
+            gdb
+            rr
+            evcxr
+            valgrind
+            renderdoc
+            just
+
+            # for this project
+            nodePackages.browser-sync
+          ];
+
+          shellHook = ''
+            export RUSTC_VERSION="$(tomlq -r .toolchain.channel rust-toolchain.toml)"
+            export PATH="$PATH:''${CARGO_HOME:-~/.cargo}/bin"
+            export PATH="$PATH:''${RUSTUP_HOME:-~/.rustup/toolchains/$RUSTC_VERSION-x86_64-unknown-linux/bin}"
+            export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:${
+              builtins.toString (pkgs.lib.makeLibraryPath buildInputs)
+            }";
+
+            # for this project
+            cargo install cargo-docs-rs
+
+            rustup default $RUSTC_VERSION
+            rustup toolchain add nightly
+            rustup component add rust-src rust-analyzer
+
+          '';
         };
       });
 }
diff --git a/scopegraphs-macros/Cargo.toml b/scopegraphs-macros/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "scopegraphs-macros"
-version = "0.2.9"
+version = "0.2.13"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 authors = [
@@ -20,7 +20,7 @@ proc-macro = true
 [dependencies]
 syn = { version = "2.0.29", features = [] }
 quote = "1.0.33"
-scopegraphs-regular-expressions = { path = "../scopegraphs-regular-expressions", features = ["dot"], version = "0.2.0" }
+scopegraphs-regular-expressions = { path = "../scopegraphs-regular-expressions", features = ["dot"], version = "0.2" }
 proc-macro2 = "1.0.69"
 
 [dev-dependencies]

diff --git a/scopegraphs-regular-expressions/Cargo.toml b/scopegraphs-regular-expressions/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "scopegraphs-regular-expressions"
-version = "0.2.10"
+version = "0.2.13"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 authors = [

diff --git a/scopegraphs-render-docs/.gitignore b/scopegraphs-render-docs/.gitignore
@@ -0,0 +1,6 @@
+**/target
+**/*.rs.bk
+Cargo.lock
+.idea/
+
+render-docs
diff --git a/scopegraphs-render-docs/CHANGELOG.md b/scopegraphs-render-docs/CHANGELOG.md
@@ -0,0 +1,149 @@
+<a name="v0.5.0"></a>
+### v0.5.0 (2024-01-12)
+
+#### Breaking Changes
+
+* include_mmd! now always uses CARGO_MANIFEST_DIR as root (PR #47 by [Rjected](https://github.com/Rjected))
+
+#### Miscellaneous
+
+<a name="v0.4.0"></a>
+### v0.4.0 (2023-12-13) YANKED
+
+#### Breaking Changes
+
+* `path` attribute is no longer supported for importing diagrams from external files
+
+#### Features
+
+*   `include_mmd!` macro-like syntax for embedding diagrams from files
+*   multiple diagrams can now be imported from filesystem per documented entity
+*   imported diagrams can now be placed freely at any place inside the doc comment
+
+#### Miscellaneous
+
+*   syn bumped to version 2 (PR #42 by [maurer](https://github.com/maurer)
+
+<a name="v0.3.1"></a>
+### v0.3.1 (2023-04-17)
+
+#### Features
+
+*   mermaid is updated to v10 (PR #46 by [frehberg](https://github.com/frehberg))
+*   better handling of a failure to load mermaidjs (PR #46 by [frehberg](https://github.com/frehberg))
+
+#### Miscellaneous
+
+*   add Frehberg as a maintainer on GitHub, and package owner on Crates.io
+
+<a name="v0.3.0"></a>
+### v0.3.0 (2023-02-16)
+
+#### Maintenance
+
+*   update dependencies
+
+<a name="v0.2.2"></a>
+### v0.2.2 (2023-02-02)
+
+#### Bug Fixes
+
+*   gracefully handle failure to write mermaid.js files ([514c67c9](514c67c9))
+
+<a name="v0.2.1"></a>
+### v0.2.1 (2023-02-01)
+
+#### Maintenance 
+
+*   MermaidJS updated to version 9.3.0 
+
+<a name="v0.2.0"></a>
+## v0.2.0 (2023-01-31)
+
+#### Bug Fixes
+
+*   embedding broken when dependants are built with `--no-deps` [06e263b3](06e263b3) by [frehberg](https://github.com/frehberg)
+
+#### Features
+
+*   allow loading diagrams from filesystem via macro attrs [0eb7e08f](0eb7e08f) by [drbh](https://github.com/drbh)
+
+<a name="v0.1.12"></a>
+### v0.1.12 (2022-08-17)
+
+mermaid.js upgraded to version 9.1.4
+
+#### Bug Fixes
+
+*   failing doctest ([680ea555](680ea555))
+*   typo in changelog ([75419467](75419467))
+
+
+<a name="0.1.11"></a>
+## 0.1.11 (2021-05-31)
+
+
+#### Features
+
+*   verbose mermaid.js logging ([33746ab3](33746ab3)) by [yunhong](https://github.com/allenchou13)
+*   mermaid.js version 13.4 ([33746ab3](33746ab3)) by [yunhong](https://github.com/allenchou13)
+
+<a name="0.1.10"></a>
+## 0.1.10 (2021-05-31)
+
+
+#### Features
+
+*   lower MSRV to 1.31.1 ([2fd0f032](2fd0f032))
+
+<a name="0.1.9"></a>
+## 0.1.9 (2021-05-15)
+
+#### Features
+
+*   upgrade mermaid.js to 8.10.1 ([fbb13e1db](fbb13e1db)) by [José Duarte](https://github.com/jmg-duarte)
+
+<a name="0.1.8"></a>
+## 0.1.8 (2021-04-08)
+
+#### Bug Fixes
+
+*   fallback to CDN version of mermaid.js if local isn't found ([de9f274e](de9f274e))
+
+<a name="0.1.7"></a>
+## 0.1.7 (2021-04-08)
+
+#### Features
+
+*   use local version of the mermaid.js library ([8f523072](8f523072)) by [Le Savon Fou](https://github.com/lesavonfou)
+
+#### Bug Fixes
+
+*   fix doctests ([ea685563](ea685563)) by [Le Savon Fou](https://github.com/lesavonfou)
+
+<a name="0.1.6"></a>
+## 0.1.6 (2021-01-28)
+
+
+#### Bug Fixes
+
+*   use regex to detect the dark themes reliably on docs.rs ([ce24cd6e](ce24cd6e))
+
+
+<a name="0.1.5"></a>
+## 0.1.5 (2021-01-28)
+
+
+#### Bug Fixes
+
+*   initialization script wasn't firing at page load ([36268718](36268718))
+
+
+<a name="0.1.4"></a>
+## 0.1.4 (2021-01-28)
+
+
+#### Features
+
+*   dark mode and custom themes ([62ec6783](62ec6783))
+*   add crossorigin attribute to script tag ([fa9f4546](fa9f4546)) by [Mark Schmale](https://github.com/themasch)
diff --git a/scopegraphs-render-docs/Cargo.toml b/scopegraphs-render-docs/Cargo.toml
@@ -0,0 +1,26 @@
+[package]
+name = "scopegraphs-render-docs"
+version = "0.2.18"
+authors = ["Mike Lubinets <[email protected]>", "Frank Rehberger <[email protected]>", "Jonathan Dönszelmann <[email protected]>"]
+description = "Derived from Aquamarine, a mermaid.js integration for rustdoc, renders scopegraphs by executing doctests to generate mermaid"
+keywords = ["proc_macro", "docs", "rustdoc", "mermaid", "diagram"]
+categories = ["visualization", "development-tools::build-utils"]
+repository = "https://github.com/metaborg/rust-scopegraphs/"
+edition = "2018"
+license = "MIT"
+include = ["src/**/*", "Cargo.toml", "doc/js/**"]
+
+[lib]
+proc-macro = true
+
+[dependencies]
+quote = "1"
+proc-macro2 = "1"
+proc-macro-error = { version = "1", default-features = false }
+itertools = "0.10"
+syn = "2"
+include_dir = "0.7"
+uuid = { version = "1.8.0", features = ["v4"] }
+
+[dev-dependencies]
+pretty_assertions = "1"
diff --git a/scopegraphs-render-docs/LICENSE b/scopegraphs-render-docs/LICENSE
@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Mike Lubinets <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.