Merge pull request #2874 from ehuss/cmd-docs

Remove partially outdated CmdPreprocessor/CmdRenderer docs

crates/mdbook-driver/src/builtin_preprocessors/cmd.rs

@@ -8,27 +8,8 @@ use tracing::{debug, trace, warn};
 
 /// A custom preprocessor which will shell out to a 3rd-party program.
 ///
-/// # Preprocessing Protocol
+/// See <https://rust-lang.github.io/mdBook/for_developers/preprocessors.html>
-///
+/// for a description of the preprocessor protocol.
-/// When the `supports_renderer()` method is executed, `CmdPreprocessor` will
-/// execute the shell command `$cmd supports $renderer`. If the renderer is
-/// supported, custom preprocessors should exit with a exit code of `0`,
-/// any other exit code be considered as unsupported.
-///
-/// The `run()` method is implemented by passing a `(PreprocessorContext, Book)`
-/// tuple to the spawned command (`$cmd`) as JSON via `stdin`. Preprocessors
-/// should then "return" a processed book by printing it to `stdout` as JSON.
-/// For convenience, the `CmdPreprocessor::parse_input()` function can be used
-/// to parse the input provided by `mdbook`.
-///
-/// Exiting with a non-zero exit code while preprocessing is considered an
-/// error. `stderr` is passed directly through to the user, so it can be used
-/// for logging or emitting warnings if desired.
-///
-/// # Examples
-///
-/// An example preprocessor is available in this project's `examples/`
-/// directory.
 #[derive(Debug, Clone, PartialEq)]
 pub struct CmdPreprocessor {
     name: String,

crates/mdbook-driver/src/builtin_renderers/mod.rs

@@ -14,27 +14,8 @@ mod markdown_renderer;
 
 /// A generic renderer which will shell out to an arbitrary executable.
 ///
-/// # Rendering Protocol
+/// See <https://rust-lang.github.io/mdBook/for_developers/backends.html>
-///
+/// for a description of the renderer protocol.
-/// When the renderer's `render()` method is invoked, `CmdRenderer` will spawn
-/// the `cmd` as a subprocess. The `RenderContext` is passed to the subprocess
-/// as a JSON string (using `serde_json`).
-///
-/// > **Note:** The command used doesn't necessarily need to be a single
-/// > executable (i.e. `/path/to/renderer`). The `cmd` string lets you pass
-/// > in command line arguments, so there's no reason why it couldn't be
-/// > `python /path/to/renderer --from mdbook --to epub`.
-///
-/// Anything the subprocess writes to `stdin` or `stdout` will be passed through
-/// to the user. While this gives the renderer maximum flexibility to output
-/// whatever it wants, to avoid spamming users it is recommended to avoid
-/// unnecessary output.
-///
-/// To help choose the appropriate output level, the `MDBOOK_LOG` environment
-/// variable will be passed through to the subprocess, if set.
-///
-/// If the subprocess wishes to indicate that rendering failed, it should exit
-/// with a non-zero return code.
 #[derive(Debug, Clone, PartialEq)]
 pub struct CmdRenderer {
     name: String,