Merge pull request #140 from roberth/minimal-output

feat: Minimal format

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## Upcoming release
+
+Add `--anchor-prefix` to remove or customize the `function-library-` prefix.
+
+A header won't be rendered when `--description` and `--category` are empty.
+This makes the generated markdown more flexible for inclusion in other documents.
+
+## Version 3.0.8
+
+Add `--json-output`, providing a JSON representation of the documentation.
+
+Fix: attrsets in patterns are now skipped correctly.
+
 ## Version 3.0.7
 
 Add support for empty prefix flags.

README.md

@@ -60,6 +60,15 @@ The following is an example of markdown documentation for new and current users
 
 > Note: Within nixpkgs the convention of using [definition-lists](https://www.markdownguide.org/extended-syntax/#definition-lists) for documenting arguments has been established.
 
+## Usage
+
+Refer to `nixdoc --help` for the most up-to-date usage information.
+
+For a minimal format, suitable for inclusion into a dedicated documentation page, use:
+
+```sh
+nixdoc --file lib.nix --category "" --description "" --prefix "" --anchor-prefix "" >lib.md
+```
 
 ## Custom nixdoc format (Legacy)
 

src/commonmark.rs

@@ -158,11 +158,17 @@ impl ManualEntry {
     }
 
     /// Write a single CommonMark entry for a documented Nix function.
-    pub fn write_section(self, output: &mut String) -> String {
+    ///
+    /// # Arguments
+    ///
+    /// - `anchor_prefix`: The prefix to use for the anchor links.
+    ///   In Nixpkgs this would be "function-library-".
+    /// - `output`: The output string to append the CommonMark onto.
+    pub fn write_section(self, anchor_prefix: &str, output: &mut String) -> String {
         let (ident, title) = self.get_ident_title();
         output.push_str(&format!(
-            "## `{}` {{#function-library-{}}}\n\n",
-            title, ident
+            "## `{}` {{#{}{}}}\n\n",
+            title, anchor_prefix, ident
         ));
 
         // <subtitle> (type signature)
@@ -193,8 +199,8 @@ impl ManualEntry {
         // examples, how can this be achieved automatically?
         if let Some(example) = &self.example {
             output.push_str(&format!(
-                "::: {{.example #function-library-example-{}}}\n",
-                ident
+                "::: {{.example #{}example-{}}}\n",
+                anchor_prefix, ident
             ));
             output.push_str(&format!("# `{}` usage example\n\n", title));
             output.push_str(&format!("```nix\n{}\n```\n:::\n\n", example.trim()));

src/main.rs

@@ -55,6 +55,9 @@ struct Options {
     #[arg(short, long, default_value_t = String::from("lib"))]
     prefix: String,
 
+    #[arg(long, default_value_t = String::from("function-library-"))]
+    anchor_prefix: String,
+
     /// Whether to output JSON.
     #[arg(short, long, default_value_t = false)]
     json_output: bool,
@@ -310,6 +313,9 @@ fn collect_entries(
 }
 
 fn retrieve_description(nix: &rnix::Root, description: &str, category: &str) -> String {
+    if description.is_empty() && category.is_empty() {
+        return String::new();
+    }
     format!(
         "# {} {{#sec-functions-library-{}}}\n{}\n",
         description,
@@ -351,7 +357,7 @@ fn main_with_options(opts: Options) -> String {
         let mut output = description + "\n";
 
         for entry in entries {
-            entry.write_section(&mut output);
+            entry.write_section(opts.anchor_prefix.as_str(), &mut output);
         }
         output
     }