feat: Watching Bugs & Meta

.github/workflows/rust.yml

@@ -17,32 +17,30 @@ jobs:
       #     target: x86_64-unknown-linux-gnu
       #     default: true
       #     profile: default
-      - name: Get dependency information
+      - name: Checkout codebase
+        uses: actions/checkout@v4
+      - name: Check the current Grass version
         run: |
-            gh api /repos/emmyoh/vox/commits/master --jq '.sha' > vox_rev
             curl https://crates.io/api/v1/crates/grass > grass_rev
       - name: Restore Cargo cache
         id: cache-cargo
         uses: actions/cache@v1
         with:
             path: ~/.cargo
-            key: ${{ runner.os }}-cargo-${{ hashFiles('vox_rev', 'grass_rev') }}
+            key: ${{ runner.os }}-cargo-${{ hashFiles('src/**/*', '.cargo/**/*', 'Cargo.toml', 'rust-toolchain.toml', 'grass_rev') }}
             restore-keys: |
-                ${{ runner.os }}-cargo-${{ hashFiles('vox_rev', 'grass_rev') }}
+                ${{ runner.os }}-cargo-${{ hashFiles('src/**/*', '.cargo/**/*', 'Cargo.toml', 'rust-toolchain.toml', 'grass_rev') }}
       - if: ${{ steps.cache-cargo.outputs.cache-hit != 'true' }}
-        name: Install Grass and Vox
+        name: Install Vox and Grass
         run: |
-            rm vox_rev
-            rm grass_rev
             rustup update nightly && rustup default nightly
+            time cargo install --path . --features="cli"
             time cargo install grass
-            time cargo install --git https://github.com/emmyoh/vox --features="cli"
-      - name: Checkout codebase
-        uses: actions/checkout@v4
       - name: Generate documentation
         run: time cargo doc --no-deps -Zrustdoc-map --release --quiet
       - name: Build site
         run: |
+          rm grass_rev
           mkdir -p site/output
           cp -r target/doc/* site/output/
           cd site

site/assets/style/_variables.scss

@@ -52,7 +52,7 @@
 @media (prefers-color-scheme: dark) {
   :root {
     --body-color: var(--gray-300);
-    --body-bg: var(--gray-800);
+    --body-bg: var(--gray-900);
 
     --heading-color: #fff;
 

site/diary/dag_watching.vox

@@ -7,17 +7,17 @@ permalink = "date"
 
 {% markdown %}
 
-# Notes
+## Notes
 I've been using two particular terminal invocations frequently.
 
-## Linting & formatting
+### Linting & formatting
 ```sh
 cargo fix --edition --edition-idioms --allow-dirty; cargo clippy --fix -Z unstable-options --allow-dirty; cargo fix --edition --edition-idioms --bin vox --features="cli" --allow-dirty; cargo clippy --fix -Z unstable-options --bin vox --features="cli" --allow-dirty; cargo fmt
 ```
 
 These commands lint Vox, check it for errors, and then format its code.
 
-## Installing the local copy of Vox
+### Installing the local copy of Vox
 ```sh
 cargo install --path . --features="cli"
 ```
@@ -26,7 +26,7 @@ This command allows me to use the `vox` CLI built with my latest local changes.
 
 ---
 
-# Goals
+## Goals
 
 Today, I'm concerned with:
 - Colouring pages differently when visualising the DAG; currently, the same colour is used for all pages.
@@ -35,17 +35,17 @@ Today, I'm concerned with:
 - Putting together this development diary.
 - Adding a `meta` templating context.
 
-## DAG Visualisation
+### DAG Visualisation
 Colouring should be done based on the node's label.
 To me, beige (ie, a light orange) is the colour of layouts, and a light blue complement is appropriate for collection-less pages.
 - If the page is a layout page, set its colour to beige (<img src="https://placehold.co/15x15/FFDFBA/FFDFBA.png" alt="#FFDFBA" style="margin-bottom: auto;display: inline;">).
 - If the page is a page in a collection, set its colour to light green (<img src="https://placehold.co/15x15/DAFFBA/DAFFBA.png" alt="#DAFFBA" style="margin-bottom: auto;display: inline;">).
 - If the page is a page not in a collection, set its colour to light blue (<img src="https://placehold.co/15x15/BADAFF/BADAFF.png" alt="#BADAFF" style="margin-bottom: auto;display: inline;">).
 
-## CLI Path Parameter
+### CLI Path Parameter
 The CLI should take an `Option<PathBuf>`. If this path is `None`, do nothing. Otherwise, use this path to set the current environment path.
 
-## Watching
+### Watching
 If changes are made, wait until a certain period (eg, five seconds) has elapsed where no further changes have been made.
 When such a period has elapsed, do the following:
 
@@ -65,7 +65,7 @@ When such a period has elapsed, do the following:
     - In the new DAG, replace all pages not needing rendering with their rendered counterparts from the old DAG.
 5. Render & output the appropriate pages.
 
-## Development Diary
+### Development Diary
 Maintaining a development diary is important for three primary reasons:
 1. It conveys to others that the project is being developed.
 2. It aids me in returning to the project when my attention temporarily turned away from in-progress work.
@@ -79,7 +79,7 @@ To build this development diary, I'll need to perform the following tasks:
 
 To publish this development diary, I'll use a GitHub workflow similar to the one I wrote for [`vox-basic`](https://github.com/emmyoh/vox-basic).
 
-## `meta` Context
+### `meta` Context
 The `meta` context comprises the following:
 - `meta.date`, being the current date-time of the build.
 - `meta.builder`, being the name of the software building the site ('Vox').
@@ -92,7 +92,7 @@ This makes Vox (and the abstract 'standard' it describes) very opinionated; it s
 
 ---
 
-# Future Goals
+## Future Goals
 
 In the future, this tool needs:
 1. A blog pertaining to the project, very similar in appearance to the development diary, but different in scope.

site/diary/watching_bugs.vox

@@ -0,0 +1,58 @@
+---
+title = "Watching Bugs & Meta"
+date = 2024-05-30T00:00:00+00:00
+layout = "post"
+permalink = "date"
+---
+
+{% markdown %}
+
+## Goals
+
+Today's agenda:
+- Fixing how page removal is handled while watching for changes.
+- Investigating a bug during watching where only the most recently rendered collection page will be rendered to its children.
+- Adding a `meta` context.
+- Improving the GitHub workflow for publishing this site.
+
+### Page Removal
+
+When computing which pages need rendering, we need to consider the following: if the removed page is a parent, the pages that once depended on it need to be re-rendered.
+Additionally, removed pages should have their outputs deleted.
+
+### Collection Page Rendering Lost
+
+This bug arose from improperly merging DAGs.
+
+### `meta` Context
+
+The `meta` context comprises the following:
+- `meta.date`, being the current date-time of the build.
+- `meta.builder`, being the name of the software building the site ('Vox').
+- `meta.version`, being the current version number of Vox.
+
+This was added when retrieving the {% raw %}{{ global }}{% endraw %} context.
+
+### GitHub Workflow
+
+Since this site exists in the same Git repository as Vox itself, it is not useful to pin the latest installation of Vox to the latest Git commit.
+Instead, Vox should be considered out-of-date when any of the following are changed:
+- `src` folder
+- `.cargo` folder
+- `Cargo.toml` file
+- `rust-toolchain.toml` file
+
+---
+
+## Future Goals
+- Re-rendering when layouts are modified during watching.
+- Including the contexts of all parent layouts when rendering.
+- Finishing the user guide.
+- Pointing site pages to indices, setting appropriate HTML titles.
+- Implementing partial date-times.
+- Parallelising both rendering and writing to disk.
+- Documenting the CLI code.
+- Creating a logo for Vox.
+- Updating all dependent crates.
+
+{% endmarkdown %}

site/guide/cli.vox

@@ -2,4 +2,42 @@
 title = "Command-Line Interface"
 layout = "page"
 permalink = "none"
----
+---
+
+{% markdown %}
+Vox has two subcommands: `vox build` and `vox serve`.
+
+## Building
+
+To build a site, invoke `vox build`. This command takes an optional path argument, if not building a site in the current working directory.\
+This command takes the following options:
+* `-w` or `--watch`: will watch for changes.
+* `-v` or `--verbosity`: sets the maximum level of logging output.
+    - `-v`: recoverable errors
+    - `-vv`: warnings
+    - `-vvv`: information
+    - `-vvvv`: debugging information
+    - `-vvvvv`: trace information
+* `-d` or `--visualise-dag`: will output a visualisation of the DAG to `dag.svg`.
+
+### Example
+
+To build from the current working directory while watching, visualising the DAG, and logging everything:
+```sh
+vox build -w -d -vvvvv
+```
+
+## Serving
+
+When `vox serve` is invoked, the site is first built, then served locally.\
+This command takes the same arguments and flags as `vox build`, as well as the following additional options:
+* `-p <PORT>` or `--port <PORT>`: the port to serve on (defaults to `80`).
+
+### Example
+
+To serve from `./site` on port `8080` while watching, visualising the DAG, and logging errors & warnings:
+```sh
+vox serve -p 8080 -w -d -vv ./site
+```
+
+{% endmarkdown %}

site/guide/pipeline.vox

@@ -26,7 +26,7 @@ When changes are made, rebuilding can be done selectively:
         - Their descendants in the new DAG also need to be rendered.
     - All pages that were added need to be rendered.
         - Their descendants in the new DAG also need to be rendered.
-    - All pages that were removed need their descendants in the old DAG rendered.
+    - All pages that were removed need their descendants in the new DAG rendered.
 4. The DAGs are merged.
     - In the new DAG, all pages not needing rendering are replaced with their rendered counterparts from the old DAG.
 5. Pages are rendered.

site/layouts/default.vox

@@ -16,7 +16,7 @@
       </main>
       <footer class="footer">
         <small>
-          &copy; {{ global.author }}
+          &copy; {{ global.author }} <time datetime="{{ meta.date.rfc_2822 }}">{{ meta.date.year }}</time>
         </small>
       </footer>
     </div>

src/builds.rs

@@ -1,5 +1,6 @@
 use crate::page::Page;
 use ahash::AHashMap;
+use chrono::Locale;
 use daggy::{
     petgraph::{
         dot::{Config, Dot},
@@ -25,7 +26,7 @@ pub struct Build {
     /// The Liquid contexts necessary to render templates in pages.
     pub contexts: Object,
     /// The locale information of the build, primarily used to render dates and times.
-    pub locale: String,
+    pub locale: Locale,
     /// A directed acyclic graph (DAG) populated with pages and their children.
     pub dag: StableDag<Page, EdgeType>,
 }
@@ -47,7 +48,14 @@ impl Build {
             dag_graph,
             &[Config::NodeNoLabel, Config::EdgeNoLabel],
             &|_graph, edge| format!("label = \"{:?}\"", edge.weight()),
-            &|_graph, node| format!("label = \"{}\"", node.1.to_path_string()),
+            &|_graph, node| {
+                let path = PathBuf::from(node.1.to_path_string());
+                let relative_path = path
+                    .strip_prefix(fs::canonicalize(env::current_dir().unwrap()).unwrap())
+                    .unwrap();
+                let label = relative_path.to_string_lossy().to_string();
+                format!("label = \"{}\"", label)
+            },
         );
         debug!("DAG: {:#?}", dag_graphviz);
         let mut parser = DotParser::new(&format!("{:?}", dag_graphviz));
@@ -203,20 +211,22 @@ impl Build {
                 }
                 // If the parent page is in a collection this page depends on, make note of it.
                 EdgeType::Collection => {
-                    let parent_path =
-                        fs::canonicalize(PathBuf::from(parent_page.directory.clone()))
-                            .into_diagnostic()?;
-                    let parent_path_difference = parent_path
-                        .strip_prefix(&current_directory)
-                        .into_diagnostic()?;
-                    let path_components: Vec<String> = parent_path_difference
-                        .components()
-                        .map(|c| c.as_os_str().to_string_lossy().to_string())
-                        .collect();
-                    let collection_name = path_components[0].clone();
+                    // let parent_path =
+                    //     fs::canonicalize(PathBuf::from(parent_page.directory.clone()))
+                    //         .into_diagnostic()?;
+                    let parent_path = parent_page.to_path_string();
+                    let collection_name = parent_page.get_collection_name()?.unwrap();
+                    // let parent_path_difference = parent_path
+                    //     .strip_prefix(&current_directory)
+                    //     .into_diagnostic()?;
+                    // let path_components: Vec<String> = parent_path_difference
+                    //     .components()
+                    //     .map(|c| c.as_os_str().to_string_lossy().to_string())
+                    //     .collect();
+                    // let collection_name = path_components[0].clone();
                     info!(
                         "Parent page ({:?}) is in collection: {:?}",
-                        parent_path_difference, collection_name
+                        parent_path, collection_name
                     );
                     if collection_pages.contains_key(&collection_name) {
                         collection_pages