Fix and adjust docs (#530)
This commit is contained in:
parent
80e18ea145
commit
5c63a99013
|
@ -1 +1,3 @@
|
||||||
Cargo.lock merge=binary
|
Cargo.lock merge=binary
|
||||||
|
doc/watchexec.* merge=binary
|
||||||
|
completions/* merge=binary
|
||||||
|
|
|
@ -16,7 +16,7 @@ include!(env!("BOSION_PATH"));
|
||||||
/// change is detected (among other event sources). By default, watchexec uses efficient
|
/// change is detected (among other event sources). By default, watchexec uses efficient
|
||||||
/// kernel-level mechanisms to watch for changes.
|
/// kernel-level mechanisms to watch for changes.
|
||||||
///
|
///
|
||||||
/// At startup, the specified <COMMAND> is run once, and watchexec begins monitoring for changes.
|
/// At startup, the specified command is run once, and watchexec begins monitoring for changes.
|
||||||
///
|
///
|
||||||
/// Examples:
|
/// Examples:
|
||||||
///
|
///
|
||||||
|
|
|
@ -9,8 +9,14 @@ _Watchexec's event types._
|
||||||
[docs]: https://docs.rs/watchexec-events
|
[docs]: https://docs.rs/watchexec-events
|
||||||
[license]: ../../LICENSE
|
[license]: ../../LICENSE
|
||||||
|
|
||||||
This is particularly useful if you're building a tool that runs under Watchexec, and want to easily
|
Fundamentally, events in watchexec have three purposes:
|
||||||
read its events (with `--emit-events-to=json-file` and `--emit-events-to=json-stdin`).
|
|
||||||
|
1. To trigger the launch, restart, or other interruption of a process;
|
||||||
|
2. To be filtered upon according to whatever set of criteria is desired;
|
||||||
|
3. To carry information about what caused the event, which may be provided to the process.
|
||||||
|
|
||||||
|
Outside of Watchexec, this library is particularly useful if you're building a tool that runs under
|
||||||
|
it, and want to easily read its events (with `--emit-events-to=json-file` and `--emit-events-to=json-stdin`).
|
||||||
|
|
||||||
```rust ,no_run
|
```rust ,no_run
|
||||||
use std::io::{stdin, Result};
|
use std::io::{stdin, Result};
|
||||||
|
|
|
@ -1,10 +1,4 @@
|
||||||
//! Synthetic event type, derived from inputs, triggers actions.
|
#![doc = include_str!("../README.md")]
|
||||||
//!
|
|
||||||
//! Fundamentally, events in watchexec have three purposes:
|
|
||||||
//!
|
|
||||||
//! 1. To trigger the launch, restart, or other interruption of a process;
|
|
||||||
//! 2. To be filtered upon according to whatever set of criteria is desired;
|
|
||||||
//! 3. To carry information about what caused the event, which may be provided to the process.
|
|
||||||
|
|
||||||
#[doc(inline)]
|
#[doc(inline)]
|
||||||
pub use event::*;
|
pub use event::*;
|
||||||
|
|
|
@ -23,7 +23,7 @@ use crate::{IgnoreFile, IgnoreFilter};
|
||||||
///
|
///
|
||||||
/// Importantly, this should be called from the origin of the project, not a subfolder. This
|
/// Importantly, this should be called from the origin of the project, not a subfolder. This
|
||||||
/// function will not discover the project origin, and will not traverse parent directories. Use the
|
/// function will not discover the project origin, and will not traverse parent directories. Use the
|
||||||
/// [`project::origins`](crate::project::origins) function for that.
|
/// `project-origins` crate for that.
|
||||||
///
|
///
|
||||||
/// This function also does not distinguish between project folder types, and collects all files for
|
/// This function also does not distinguish between project folder types, and collects all files for
|
||||||
/// all supported VCSs and other project types. Use the `applies_to` field to filter the results.
|
/// all supported VCSs and other project types. Use the `applies_to` field to filter the results.
|
||||||
|
|
|
@ -33,7 +33,7 @@ pub enum Error {
|
||||||
// TODO: extract glob error into diagnostic
|
// TODO: extract glob error into diagnostic
|
||||||
},
|
},
|
||||||
|
|
||||||
/// Multiple related [`Error`]s.
|
/// Multiple related [`Error`](enum@Error)s.
|
||||||
#[error("multiple: {0:?}")]
|
#[error("multiple: {0:?}")]
|
||||||
#[diagnostic(code(ignore_file::set))]
|
#[diagnostic(code(ignore_file::set))]
|
||||||
Multi(#[related] Vec<Error>),
|
Multi(#[related] Vec<Error>),
|
||||||
|
|
|
@ -14,7 +14,7 @@ use crate::{Error, IgnoreFile};
|
||||||
///
|
///
|
||||||
/// This reads and compiles ignore files, and should be used for handling ignore files. It's created
|
/// This reads and compiles ignore files, and should be used for handling ignore files. It's created
|
||||||
/// with a project origin and a list of ignore files, and new ignore files can be added later
|
/// with a project origin and a list of ignore files, and new ignore files can be added later
|
||||||
/// (unless [`finish`](IgnoreFilterer::finish()) is called).
|
/// (unless [`finish`](IgnoreFilter::finish()) is called).
|
||||||
#[derive(Clone, Debug)]
|
#[derive(Clone, Debug)]
|
||||||
pub struct IgnoreFilter {
|
pub struct IgnoreFilter {
|
||||||
origin: PathBuf,
|
origin: PathBuf,
|
||||||
|
@ -25,7 +25,7 @@ pub struct IgnoreFilter {
|
||||||
impl IgnoreFilter {
|
impl IgnoreFilter {
|
||||||
/// Create a new empty filterer.
|
/// Create a new empty filterer.
|
||||||
///
|
///
|
||||||
/// Prefer [`new()`](IgnoreFilterer::new()) if you have ignore files ready to use.
|
/// Prefer [`new()`](IgnoreFilter::new()) if you have ignore files ready to use.
|
||||||
pub fn empty(origin: impl AsRef<Path>) -> Self {
|
pub fn empty(origin: impl AsRef<Path>) -> Self {
|
||||||
let origin = origin.as_ref();
|
let origin = origin.as_ref();
|
||||||
Self {
|
Self {
|
||||||
|
@ -37,7 +37,7 @@ impl IgnoreFilter {
|
||||||
|
|
||||||
/// Read ignore files from disk and load them for filtering.
|
/// Read ignore files from disk and load them for filtering.
|
||||||
///
|
///
|
||||||
/// Use [`empty()`](IgnoreFilterer::empty()) if you want an empty filterer,
|
/// Use [`empty()`](IgnoreFilter::empty()) if you want an empty filterer,
|
||||||
/// or to construct one outside an async environment.
|
/// or to construct one outside an async environment.
|
||||||
pub async fn new(origin: impl AsRef<Path> + Send, files: &[IgnoreFile]) -> Result<Self, Error> {
|
pub async fn new(origin: impl AsRef<Path> + Send, files: &[IgnoreFile]) -> Result<Self, Error> {
|
||||||
let origin = origin.as_ref();
|
let origin = origin.as_ref();
|
||||||
|
@ -219,8 +219,8 @@ impl IgnoreFilter {
|
||||||
///
|
///
|
||||||
/// Returns `false` if the folder should be ignored.
|
/// Returns `false` if the folder should be ignored.
|
||||||
///
|
///
|
||||||
/// Note that this is a slightly different implementation than the [`Filterer`] trait, as the
|
/// Note that this is a slightly different implementation than watchexec's Filterer trait, as
|
||||||
/// latter handles events with multiple associated paths.
|
/// the latter handles events with multiple associated paths.
|
||||||
pub fn check_dir(&self, path: &Path) -> bool {
|
pub fn check_dir(&self, path: &Path) -> bool {
|
||||||
let _span = trace_span!("check_dir", ?path).entered();
|
let _span = trace_span!("check_dir", ?path).entered();
|
||||||
|
|
||||||
|
|
|
@ -9,6 +9,62 @@ use crate::{
|
||||||
|
|
||||||
/// Errors which _may_ be recoverable, transient, or only affect a part of the operation, and should
|
/// Errors which _may_ be recoverable, transient, or only affect a part of the operation, and should
|
||||||
/// be reported to the user and/or acted upon programatically, but will not outright stop watchexec.
|
/// be reported to the user and/or acted upon programatically, but will not outright stop watchexec.
|
||||||
|
///
|
||||||
|
/// Some errors that are classified here are spurious and may be ignored; in general you should not
|
||||||
|
/// use the convenience print handlers for handling these errors beyond prototyping. For example,
|
||||||
|
/// "waiting on process" errors should not be printed to the user by default:
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// # use std::convert::Infallible;
|
||||||
|
/// # use tracing::error;
|
||||||
|
/// # use watchexec::{config::InitConfig, ErrorHook, error::RuntimeError, handler::SyncFnHandler};
|
||||||
|
/// # let mut config = InitConfig::default();
|
||||||
|
/// config.on_error(SyncFnHandler::from(
|
||||||
|
/// |err: ErrorHook| -> std::result::Result<(), Infallible> {
|
||||||
|
/// if let RuntimeError::IoError {
|
||||||
|
/// about: "waiting on process group",
|
||||||
|
/// ..
|
||||||
|
/// } = err.error
|
||||||
|
/// {
|
||||||
|
/// error!("{}", err.error);
|
||||||
|
/// return Ok(());
|
||||||
|
/// }
|
||||||
|
///
|
||||||
|
/// // ...
|
||||||
|
///
|
||||||
|
/// Ok(())
|
||||||
|
/// },
|
||||||
|
/// ));
|
||||||
|
/// ```
|
||||||
|
///
|
||||||
|
/// On the other hand, some errors may not be fatal to this library's understanding, but will be to
|
||||||
|
/// your application. In those cases, you should "elevate" these errors, which will transform them
|
||||||
|
/// to [`CriticalError`](super::CriticalError)s:
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// # use std::convert::Infallible;
|
||||||
|
/// # use watchexec::{config::InitConfig, ErrorHook, error::{RuntimeError, FsWatcherError}, handler::SyncFnHandler};
|
||||||
|
/// # let mut config = InitConfig::default();
|
||||||
|
/// config.on_error(SyncFnHandler::from(
|
||||||
|
/// |err: ErrorHook| -> std::result::Result<(), Infallible> {
|
||||||
|
/// if let RuntimeError::FsWatcher {
|
||||||
|
/// err:
|
||||||
|
/// FsWatcherError::Create { .. }
|
||||||
|
/// | FsWatcherError::TooManyWatches { .. }
|
||||||
|
/// | FsWatcherError::TooManyHandles { .. },
|
||||||
|
/// ..
|
||||||
|
/// } = err.error
|
||||||
|
/// {
|
||||||
|
/// err.elevate();
|
||||||
|
/// return Ok(());
|
||||||
|
/// }
|
||||||
|
///
|
||||||
|
/// // ...
|
||||||
|
///
|
||||||
|
/// Ok(())
|
||||||
|
/// },
|
||||||
|
/// ));
|
||||||
|
/// ```
|
||||||
#[derive(Debug, Diagnostic, Error)]
|
#[derive(Debug, Diagnostic, Error)]
|
||||||
#[non_exhaustive]
|
#[non_exhaustive]
|
||||||
#[diagnostic(url(docsrs))]
|
#[diagnostic(url(docsrs))]
|
||||||
|
|
|
@ -88,9 +88,6 @@
|
||||||
//! printing even error log messages for this crate unless it's for debugging. Instead, make use of
|
//! printing even error log messages for this crate unless it's for debugging. Instead, make use of
|
||||||
//! the [`InitConfig::on_error()`][config::InitConfig::on_error()] method to define a handler for
|
//! the [`InitConfig::on_error()`][config::InitConfig::on_error()] method to define a handler for
|
||||||
//! errors occurring at runtime that are _meant_ for you to handle (by printing out or otherwise).
|
//! errors occurring at runtime that are _meant_ for you to handle (by printing out or otherwise).
|
||||||
//!
|
|
||||||
//! This crate does not itself use `unsafe`. However, it depends on a number of libraries which do,
|
|
||||||
//! most because they interact with the operating system.
|
|
||||||
|
|
||||||
#![doc(html_favicon_url = "https://watchexec.github.io/logo:watchexec.svg")]
|
#![doc(html_favicon_url = "https://watchexec.github.io/logo:watchexec.svg")]
|
||||||
#![doc(html_logo_url = "https://watchexec.github.io/logo:watchexec.svg")]
|
#![doc(html_logo_url = "https://watchexec.github.io/logo:watchexec.svg")]
|
||||||
|
|
|
@ -10,6 +10,7 @@ _Watchexec's signal type._
|
||||||
[license]: ../../LICENSE
|
[license]: ../../LICENSE
|
||||||
|
|
||||||
```rust
|
```rust
|
||||||
|
use std::str::FromStr;
|
||||||
use watchexec_signals::Signal;
|
use watchexec_signals::Signal;
|
||||||
|
|
||||||
fn main() {
|
fn main() {
|
||||||
|
|
|
@ -1,15 +1,4 @@
|
||||||
//! Notifications (signals or Windows control events) sent to a process.
|
#![doc = include_str!("../README.md")]
|
||||||
//!
|
|
||||||
//! This signal type in Watchexec is used for any of:
|
|
||||||
//! - signals sent to the main process by some external actor,
|
|
||||||
//! - signals received from a sub process by the main process,
|
|
||||||
//! - signals sent to a sub process by Watchexec.
|
|
||||||
//!
|
|
||||||
//! ## Features
|
|
||||||
//!
|
|
||||||
//! - `fromstr`: Enables parsing of signals from strings.
|
|
||||||
//! - `serde`: Enables [`serde`][serde] support. Note that this is stricter than string parsing.
|
|
||||||
//! - `miette`: Enables [`miette`][miette] support for [`SignalParseError`][SignalParseError].
|
|
||||||
|
|
||||||
use std::fmt;
|
use std::fmt;
|
||||||
|
|
||||||
|
@ -19,7 +8,12 @@ use std::str::FromStr;
|
||||||
#[cfg(unix)]
|
#[cfg(unix)]
|
||||||
use nix::sys::signal::Signal as NixSignal;
|
use nix::sys::signal::Signal as NixSignal;
|
||||||
|
|
||||||
/// A notification sent to a process.
|
/// A notification (signals or Windows control events) sent to a process.
|
||||||
|
///
|
||||||
|
/// This signal type in Watchexec is used for any of:
|
||||||
|
/// - signals sent to the main process by some external actor,
|
||||||
|
/// - signals received from a sub process by the main process,
|
||||||
|
/// - signals sent to a sub process by Watchexec.
|
||||||
///
|
///
|
||||||
/// On Windows, only some signals are supported, as described. Others will be ignored.
|
/// On Windows, only some signals are supported, as described. Others will be ignored.
|
||||||
///
|
///
|
||||||
|
|
|
@ -10,7 +10,7 @@ Execute commands when watched files change.
|
||||||
.PP
|
.PP
|
||||||
Recursively monitors the current directory for changes, executing the command when a filesystem change is detected (among other event sources). By default, watchexec uses efficient kernel\-level mechanisms to watch for changes.
|
Recursively monitors the current directory for changes, executing the command when a filesystem change is detected (among other event sources). By default, watchexec uses efficient kernel\-level mechanisms to watch for changes.
|
||||||
.PP
|
.PP
|
||||||
At startup, the specified <COMMAND> is run once, and watchexec begins monitoring for changes.
|
At startup, the specified command is run once, and watchexec begins monitoring for changes.
|
||||||
.PP
|
.PP
|
||||||
Examples:
|
Examples:
|
||||||
.PP
|
.PP
|
||||||
|
|
|
@ -30,7 +30,7 @@ command when a filesystem change is detected (among other event
|
||||||
sources). By default, watchexec uses efficient kernel-level mechanisms
|
sources). By default, watchexec uses efficient kernel-level mechanisms
|
||||||
to watch for changes.
|
to watch for changes.
|
||||||
|
|
||||||
At startup, the specified \<COMMAND\> is run once, and watchexec begins
|
At startup, the specified command is run once, and watchexec begins
|
||||||
monitoring for changes.
|
monitoring for changes.
|
||||||
|
|
||||||
Examples:
|
Examples:
|
||||||
|
|
Binary file not shown.
Loading…
Reference in New Issue