feat(doc): #940 code sections

- Add code sections to all extensions - Use admonitions for notes and warnings - Add configuration for mermaid graphs Signed-off-by: Daniel Salazar <[email protected]>
fluidattacks · Mar 14, 2023 · 1f27e5a · 1f27e5a
1 parent ea69ba7
commit 1f27e5a
Show file tree

Hide file tree

Showing 14 changed files with 1,177 additions and 1,055 deletions.
diff --git a/docs/mkdocs.yaml b/docs/mkdocs.yaml
@@ -91,7 +91,11 @@ markdown_extensions:
       pygments_lang_class: true
   - pymdownx.keys
   - pymdownx.smartsymbols
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
   - pymdownx.inlinehilite
   - pymdownx.snippets
   - pymdownx.tabbed:

diff --git a/docs/src/api/builtins/test.md b/docs/src/api/builtins/test.md
@@ -39,7 +39,7 @@ Types:
 
     And we will run pytest like this:
 
-    ```{ .bash, linenums=0}
+    ```bash
     pytest /tmp/some-random-unique-dir/__project__/path/to/src
     ```
 

diff --git a/docs/src/api/extensions/containers.md b/docs/src/api/extensions/containers.md
@@ -18,7 +18,7 @@ A container image is composed of:
 
 Resources:
 
-- https://grahamc.com/blog/nix-and-layered-docker-images
+- [Nix and layered docker images](https://grahamc.com/blog/nix-and-layered-docker-images)
 
 Types:
 
@@ -36,84 +36,89 @@ Types:
 
 Example:
 
-```nix
-# /path/to/my/project/makes/example/main.nix
-{ inputs
-, makeContainerImage
-, makeDerivation
-, ...
-}:
-makeContainerImage {
-  config = {
-    Env = [
-      # Do not use this for sensitive values, it's not safe.
-      "EXAMPLE_ENV_VAR=example-value"
-    ];
-    WorkingDir = "/working-dir";
-  };
-  layers = [
-    inputs.nixpkgs.coreutils # ls, cat, etc
-    (makeDerivation {
-      name = "custom-layer";
-      builder = ''
-        # $out represents the final container root file system: /
-        #
-        # The following commands are equivalent in Docker to:
-        #   RUN mkdir /working-dir
-        #   RUN echo my-file-contents > /working-dir/my-file
-        #
-        mkdir -p $out/working-dir
-        echo my-file-contents > $out/working-dir/my-file
-      '';
-    })
-  ];
-}
-```
-
-```bash
-$ m . /example
-
-    Creating layer 1 from paths: ['/nix/store/zqaqyidzsqc7z03g4ajgizy2lz1m19xz-libunistring-0.9.10']
-    Creating layer 2 from paths: ['/nix/store/xjjdyb66g3cxd5880zspazsp5f16lbxz-libidn2-2.3.1']
-    Creating layer 3 from paths: ['/nix/store/wvgyhnd3rn6dhxzbr5r71gx2q9mhgshj-glibc-2.32-48']
-    Creating layer 4 from paths: ['/nix/store/ip0pxdd49l1v3cmxsvw8ziwmqhyzg5pf-attr-2.4.48']
-    Creating layer 5 from paths: ['/nix/store/26vpasbj38nhj462kqclwp2i6s3hhdba-acl-2.3.1']
-    Creating layer 6 from paths: ['/nix/store/937f5738d2frws07ixcpg5ip176pfss1-coreutils-8.32']
-    Creating layer 7 from paths: ['/nix/store/fc24830z8lqa657grb3snvjjv9vxs7ql-custom-layer']
-    Creating layer 8 with customisation...
-    Adding manifests...
-    Done.
-
-    /nix/store/dvif4xy1l0qsjblxvzzcr6map1hg22w5-container-image.tar.gz
-
-$ docker load < /nix/store/dvif4xy1l0qsjblxvzzcr6map1hg22w5-container-image.tar.gz
-
-    b5507f5bda26: Loading layer  133.1kB/133.1kB
-    da2b3a66ea19: Loading layer  1.894MB/1.894MB
-    eb4c566a2922: Loading layer  10.24kB/10.24kB
-    19b7be559bbc: Loading layer  61.44kB/61.44kB
-    Loaded image: container-image:latest
-
-$ docker run container-image:latest pwd
-
-    /working-dir
-
-$ docker run container-image:latest ls .
-
-    my-file
-
-$ docker run container-image:latest cat my-file
-
-    my-file-contents
-
-$ docker run container-image:latest ls /
-
-    bin
-    dev
-    etc
-    libexec
-    nix
-    proc
-    sys
-    working-dir
-```
+=== "main.nix"
+
+    ```nix
+    # /path/to/my/project/makes/example/main.nix
+    {
+      inputs,
+      makeContainerImage,
+      makeDerivation,
+      ...
+    }:
+    makeContainerImage {
+      config = {
+        Env = [
+          # Do not use this for sensitive values, it's not safe.
+          "EXAMPLE_ENV_VAR=example-value"
+        ];
+        WorkingDir = "/working-dir";
+      };
+      layers = [
+        inputs.nixpkgs.coreutils # ls, cat, etc
+        (makeDerivation {
+          name = "custom-layer";
+          builder = ''
+            # $out represents the final container root file system: /
+            #
+            # The following commands are equivalent in Docker to:
+            #   RUN mkdir /working-dir
+            #   RUN echo my-file-contents > /working-dir/my-file
+            #
+            mkdir -p $out/working-dir
+            echo my-file-contents > $out/working-dir/my-file
+          '';
+        })
+      ];
+    }
+    ```
+
+=== "Invocation"
+
+    ```bash
+    $ m . /example
+
+        Creating layer 1 from paths: ['/nix/store/zqaqyidzsqc7z03g4ajgizy2lz1m19xz-libunistring-0.9.10']
+        Creating layer 2 from paths: ['/nix/store/xjjdyb66g3cxd5880zspazsp5f16lbxz-libidn2-2.3.1']
+        Creating layer 3 from paths: ['/nix/store/wvgyhnd3rn6dhxzbr5r71gx2q9mhgshj-glibc-2.32-48']
+        Creating layer 4 from paths: ['/nix/store/ip0pxdd49l1v3cmxsvw8ziwmqhyzg5pf-attr-2.4.48']
+        Creating layer 5 from paths: ['/nix/store/26vpasbj38nhj462kqclwp2i6s3hhdba-acl-2.3.1']
+        Creating layer 6 from paths: ['/nix/store/937f5738d2frws07ixcpg5ip176pfss1-coreutils-8.32']
+        Creating layer 7 from paths: ['/nix/store/fc24830z8lqa657grb3snvjjv9vxs7ql-custom-layer']
+        Creating layer 8 with customisation...
+        Adding manifests...
+        Done.
+
+        /nix/store/dvif4xy1l0qsjblxvzzcr6map1hg22w5-container-image.tar.gz
+
+    $ docker load < /nix/store/dvif4xy1l0qsjblxvzzcr6map1hg22w5-container-image.tar.gz
+
+        b5507f5bda26: Loading layer  133.1kB/133.1kB
+        da2b3a66ea19: Loading layer  1.894MB/1.894MB
+        eb4c566a2922: Loading layer  10.24kB/10.24kB
+        19b7be559bbc: Loading layer  61.44kB/61.44kB
+        Loaded image: container-image:latest
+
+    $ docker run container-image:latest pwd
+
+        /working-dir
+
+    $ docker run container-image:latest ls .
+
+        my-file
+
+    $ docker run container-image:latest cat my-file
+
+        my-file-contents
+
+    $ docker run container-image:latest ls /
+
+        bin
+        dev
+        etc
+        libexec
+        nix
+        proc
+        sys
+        working-dir
+    ```
-Original file line number
+Diff line change
@@ Expand Up / @@ -39,7 +39,7 @@ Types: @@
         And we will run pytest like this:
-        ```{ .bash, linenums=0}
+        ```bash
         pytest /tmp/some-random-unique-dir/__project__/path/to/src
         ```
@@ Expand Down @@