init: frontmatter support

Cargo.toml

@@ -12,6 +12,8 @@ serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 textwrap = "0.16"
 clap = { version = "4.4.4", features = ["derive"] }
+serde_yaml = "0.9.33"
+yaml-front-matter = "0.1.0"
 
 [dev-dependencies]
 insta = "1.36.1"

doc/frontmatter.md

@@ -0,0 +1,96 @@
+# Frontmatter
+
+This document is the specification for custom metadata within doc-comments.
+
+It should only apply to doc-comments (`/** */`) and not to regular code comments to ensure a limited scope.
+
+## Why frontmatter is needed (sometimes)
+
+Sometimes it is desireable to extend the native doc-comment functionality. For that user scenario, frontmatter can be optionally used.
+
+i.e.,
+
+- Enriching documentation generation.
+- Maintaining References.
+- Metadata inclusion.
+- Allow better Handling of edge cases.
+
+## Detailed design
+
+Fields (from Keywords list) can be defined in frontmatter.
+
+Frontmatter is defined using key-value pairs, encapsulated within triple-dashed lines (---).
+
+While there is no strict specification for frontmatter formats, YAML is commonly preferred. Although JSON could also be used alternatively.
+
+`{key}` is a placeholder for the list of available keywords listed below.
+
+`{value}` is a placeholder for the set value associated with the directive.
+
+Example:
+
+```nix
+{
+/** 
+  ---
+  import: ./path.md
+  ---
+*/
+foo = x: x;
+}
+```
+
+In this example, the `import` directive fetches content from `./path.md` treating it as if it were directly within the doc-comment.
+This allows tracking the reference between the source position and the markdown file, in case of extensive documentation.
+
+## Keywords
+
+### Import
+
+Rules:
+
+1. The `import` keyword can be used to use content from another file INSTEAD of the doc-comments content.
+
+2. The value `file` must be given as an absolute path (relative to git root) or relative to the current file.
+
+3. There can only be one `import` per doc-comment.
+
+```nix
+{
+/** 
+ ---
+ import: ./path.md
+ ---
+*/
+foo = x: x;
+}
+```
+
+`path.md`
+```md
+some nice docs!
+```
+
+Rendering this would behave as if the content where actually placed in the doc-comment itself.
+
+Placing frontmatter inside the imported file will be ignored. (No nested directives)
+Since handling recursive or nested imports adds too much complexity for little or no benefit.
+
+> Note: Absolute path imports are relative to the repository root. They only work inside `git` repositories and require having the `git` binary in PATH.
+> This is most commonly used in large repositories or when the documentation files are not placed alongside the .nix files.
+
+## Extensibility
+
+The initial set of keywords is intentionally minimalistic,
+focusing on immediate and broadly applicable needs.
+
+Community contributions are encouraged to expand this list as new use cases emerge.
+
+## Error handling
+
+Any issues encountered during the processing of frontmatter—be it syntax errors, invalid paths, or unsupported keywords—should result in clear, actionable error messages to the user.
+
+## Future work
+
+This proposal represents a foundational step towards more versatile and extendable reference documentation.
+As we move forward, we'll remain open to adapting and expanding this specification to meet emerging needs and leverage community insights.

src/frontmatter.rs

@@ -0,0 +1,61 @@
+use std::{
+    collections::HashMap,
+    fs,
+    path::{Path, PathBuf},
+    process::Command,
+};
+
+use serde::{Deserialize, Serialize};
+use yaml_front_matter::YamlFrontMatter;
+
+fn find_repo_root() -> Option<PathBuf> {
+    let output = Command::new("git")
+        .args(["rev-parse", "--show-toplevel"])
+        .output()
+        .ok()?
+        .stdout;
+
+    let path_str = String::from_utf8(output).ok()?.trim().to_string();
+    Some(PathBuf::from(path_str))
+}
+
+#[derive(Deserialize, Serialize, Debug)]
+pub struct Matter {
+    #[serde(flatten)]
+    pub content: HashMap<String, serde_yaml::Value>,
+}
+
+/// Returns the actual content of a markdown file, if the frontmatter has an import field.
+pub fn get_imported_content(file_path: &Path, markdown: Option<&String>) -> Option<String> {
+    markdown?;
+
+    match YamlFrontMatter::parse::<Matter>(markdown.unwrap()) {
+        Ok(document) => {
+            let metadata = document.metadata.content;
+
+            let abs_import = metadata.get("import").map(|field| {
+                let import_val = field
+                    .as_str()
+                    .expect("Frontmatter: import field must be a string");
+                match PathBuf::from(import_val).is_relative() {
+                    true => PathBuf::from_iter(vec![
+                        // Cannot fail because every file has a parent directory
+                        file_path.parent().unwrap().to_path_buf(),
+                        PathBuf::from(import_val),
+                    ]),
+                    false => PathBuf::from_iter(vec![
+                        find_repo_root()
+                        .expect("Could not find root directory of repository. Make sure you have git installed and are in a git repository"),
+                        PathBuf::from(format!(".{import_val}")),
+                    ]),
+                }
+            });
+
+            abs_import.map(|path| {
+                fs::read_to_string(&path)
+                    .expect(format!("Could not read file: {:?}", &path).as_str())
+            })
+        }
+        Err(_) => None,
+    }
+}

src/legacy.rs

@@ -1,3 +1,5 @@
+use std::path::Path;
+
 use rnix::{
     ast::{AstToken, Comment, Expr, Lambda, Param},
     SyntaxKind, SyntaxNode,
@@ -96,7 +98,7 @@ pub fn retrieve_legacy_comment(node: &SyntaxNode, allow_line_comments: bool) ->
 
 /// Traverse directly chained nix lambdas and collect the identifiers of all lambda arguments
 /// until an unexpected AST node is encountered.
-pub fn collect_lambda_args_legacy(mut lambda: Lambda) -> Vec<Argument> {
+pub fn collect_lambda_args_legacy(mut lambda: Lambda, file_path: &Path) -> Vec<Argument> {
     let mut args = vec![];
 
     loop {
@@ -120,7 +122,7 @@ pub fn collect_lambda_args_legacy(mut lambda: Lambda) -> Vec<Argument> {
                     .map(|entry| SingleArg {
                         name: entry.ident().unwrap().to_string(),
                         doc: handle_indentation(
-                            &retrieve_doc_comment(entry.syntax(), Some(1))
+                            &retrieve_doc_comment(entry.syntax(), Some(1), file_path)
                                 .or(retrieve_legacy_comment(entry.syntax(), true))
                                 .unwrap_or_default(),
                         ),