refactor(lib): add changelog modifier callback to run function (#922)

* feat: add changelog modifier callback to run function

* docs(lib): add docs for run methods

* chore(lint): allow tabs in doc comments

---------

Co-authored-by: Orhun Parmaksız <[email protected]>

.github/workflows/ci.yml

@@ -97,6 +97,7 @@ jobs:
             --tests --verbose --
               -D warnings
               -A clippy::literal_string_with_formatting_args
+              -A clippy::tabs_in_doc_comments
       - name: Check the pedantic lints
         uses: actions-rs/cargo@v1
         with:
@@ -137,6 +138,22 @@ jobs:
           command: fmt
           args: --all -- --check --verbose
 
+  doctest:
+    name: Doctests
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Install toolchain
+        uses: dtolnay/rust-toolchain@nightly
+        with:
+          components: rustfmt
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Check the formatting
+        uses: actions-rs/cargo@v1
+        with:
+          command: test
+          args: --doc
+
   lychee:
     name: Links
     runs-on: ubuntu-22.04

git-cliff/examples/run.rs

@@ -0,0 +1,9 @@
+use clap::Parser;
+use git_cliff::args::Opt;
+use git_cliff_core::error::Result;
+
+fn main() -> Result<()> {
+	let args = Opt::parse();
+	git_cliff::run(args)?;
+	Ok(())
+}

git-cliff/src/lib.rs

@@ -368,7 +368,51 @@ fn process_repository<'a>(
 }
 
 /// Runs `git-cliff`.
-pub fn run(mut args: Opt) -> Result<()> {
+///
+/// # Example
+///
+/// ```no_run
+/// use clap::Parser;
+/// use git_cliff::args::Opt;
+/// use git_cliff_core::error::Result;
+///
+/// fn main() -> Result<()> {
+/// 	let args = Opt::parse();
+/// 	git_cliff::run(args)?;
+/// 	Ok(())
+/// }
+/// ```
+pub fn run(args: Opt) -> Result<()> {
+	run_with_changelog_modifier(args, |_| Ok(()))
+}
+
+/// Runs `git-cliff` with a changelog modifier.
+///
+/// This is useful if you want to modify the [`Changelog`] before
+/// it's written or the context is printed (depending how git-cliff is started).
+///
+/// # Example
+///
+/// ```no_run
+/// use clap::Parser;
+/// use git_cliff::args::Opt;
+/// use git_cliff_core::error::Result;
+///
+/// fn main() -> Result<()> {
+/// 	let args = Opt::parse();
+///
+/// 	git_cliff::run_with_changelog_modifier(args, |changelog| {
+/// 		println!("Releases: {:?}", changelog.releases);
+/// 		Ok(())
+/// 	})?;
+///
+/// 	Ok(())
+/// }
+/// ```
+pub fn run_with_changelog_modifier(
+	mut args: Opt,
+	changelog_modifier: impl FnOnce(&mut Changelog) -> Result<()>,
+) -> Result<()> {
 	// Check if there is a new version available.
 	#[cfg(feature = "update-informer")]
 	check_new_version();
@@ -633,6 +677,7 @@ pub fn run(mut args: Opt) -> Result<()> {
 		}
 		Changelog::new(releases, &config)?
 	};
+	changelog_modifier(&mut changelog)?;
 
 	// Print the result.
 	let mut out: Box<dyn io::Write> = if let Some(path) = &output {