From b163094d49937839c00b080002c055a6109a3ea9 Mon Sep 17 00:00:00 2001 From: Chip Senkbeil Date: Thu, 1 Jun 2023 02:39:34 -0500 Subject: [PATCH] Update to test READMEs --- distant-auth/src/lib.rs | 6 +++++ distant-core/README.md | 39 +++------------------------ distant-core/src/lib.rs | 6 +++++ distant-local/README.md | 2 +- distant-local/src/lib.rs | 6 +++++ distant-net/src/lib.rs | 6 +++++ distant-protocol/src/lib.rs | 6 +++++ distant-ssh2/README.md | 53 +------------------------------------ distant-ssh2/src/lib.rs | 6 +++++ src/lib.rs | 6 +++++ 10 files changed, 48 insertions(+), 88 deletions(-) diff --git a/distant-auth/src/lib.rs b/distant-auth/src/lib.rs index 35aff09..8dbd627 100644 --- a/distant-auth/src/lib.rs +++ b/distant-auth/src/lib.rs @@ -1,3 +1,9 @@ +#![doc = include_str!("../README.md")] + +#[doc = include_str!("../README.md")] +#[cfg(doctest)] +pub struct ReadmeDoctests; + mod authenticator; mod handler; mod methods; diff --git a/distant-core/README.md b/distant-core/README.md index a679ca1..9b8c01f 100644 --- a/distant-core/README.md +++ b/distant-core/README.md @@ -9,18 +9,12 @@ [distant_rustc_img]: https://img.shields.io/badge/distant_core-rustc_1.64+-lightgray.svg [distant_rustc_lnk]: https://blog.rust-lang.org/2022/09/22/Rust-1.64.0.html -Library that powers the [`distant`](https://github.com/chipsenkbeil/distant) -binary. - -🚧 **(Alpha stage software) This library is in rapid development and may break or change frequently!** 🚧 - ## Details -The `distant-core` library supplies the client, manager, and server -implementations for use with the distant API in order to communicate with -remote machines and perform actions. This library acts as the primary -implementation that powers the CLI, but is also available for other extensions -like `distant-ssh2`. +The `distant-core` library supplies the client and server interfaces along with +a client implementation for distant. The library exposes an API that downstream +libraries such as `distant-local` and `distant-ssh2` can implement to provide a +distant-compatible interface. ## Installation @@ -31,31 +25,6 @@ You can import the dependency by adding the following to your `Cargo.toml`: distant-core = "0.20" ``` -## Examples - -Below is an example of connecting to a distant server over TCP without any -encryption or authentication: - -```rust -use distant_core::{ - DistantClient, - DistantChannelExt, - net::{PlainCodec, TcpClientExt}, -}; -use std::{net::SocketAddr, path::Path}; - -// Connect to a server located at example.com on port 8080 that is using -// no encryption or authentication (PlainCodec) -let addr: SocketAddr = "example.com:8080".parse().unwrap(); -let mut client = DistantClient::connect(addr, PlainCodec).await - .expect("Failed to connect"); - -// Append text to a file -// NOTE: This method comes from DistantChannelExt -client.append_file_text(Path::new("path/to/file.txt"), "new contents").await - .expect("Failed to append to file"); -``` - ## License This project is licensed under either of diff --git a/distant-core/src/lib.rs b/distant-core/src/lib.rs index 9546300..5c2da0a 100644 --- a/distant-core/src/lib.rs +++ b/distant-core/src/lib.rs @@ -1,3 +1,9 @@ +#![doc = include_str!("../README.md")] + +#[doc = include_str!("../README.md")] +#[cfg(doctest)] +pub struct ReadmeDoctests; + mod api; pub use api::*; diff --git a/distant-local/README.md b/distant-local/README.md index a44fa41..2f2c9d8 100644 --- a/distant-local/README.md +++ b/distant-local/README.md @@ -26,7 +26,7 @@ distant-local = "0.20" ## Examples -```rust +```rust,no_run // Create a server API handler to be used with the server let handler = distant_local::initialize_handler().unwrap(); ``` diff --git a/distant-local/src/lib.rs b/distant-local/src/lib.rs index ac6afbf..dc0bbc7 100644 --- a/distant-local/src/lib.rs +++ b/distant-local/src/lib.rs @@ -1,3 +1,9 @@ +#![doc = include_str!("../README.md")] + +#[doc = include_str!("../README.md")] +#[cfg(doctest)] +pub struct ReadmeDoctests; + mod api; mod constants; pub use api::LocalDistantApi; diff --git a/distant-net/src/lib.rs b/distant-net/src/lib.rs index bd0f097..3d93c8e 100644 --- a/distant-net/src/lib.rs +++ b/distant-net/src/lib.rs @@ -1,3 +1,9 @@ +#![doc = include_str!("../README.md")] + +#[doc = include_str!("../README.md")] +#[cfg(doctest)] +pub struct ReadmeDoctests; + mod authentication; pub mod client; pub mod common; diff --git a/distant-protocol/src/lib.rs b/distant-protocol/src/lib.rs index eb450e6..1da41ad 100644 --- a/distant-protocol/src/lib.rs +++ b/distant-protocol/src/lib.rs @@ -1,3 +1,9 @@ +#![doc = include_str!("../README.md")] + +#[doc = include_str!("../README.md")] +#[cfg(doctest)] +pub struct ReadmeDoctests; + mod common; mod msg; mod request; diff --git a/distant-ssh2/README.md b/distant-ssh2/README.md index 66d7f05..a7b42dd 100644 --- a/distant-ssh2/README.md +++ b/distant-ssh2/README.md @@ -26,58 +26,7 @@ You can import the dependency by adding the following to your `Cargo.toml`: ```toml [dependencies] -distant-ssh2 = "0.19" -``` - -## Examples - -Below is an example of connecting to an ssh server and translating between ssh -protocol and distant protocol: - -```rust -use distant_ssh2::{LocalSshAuthHandler, Ssh, SshOpts}; - -// Using default ssh arguments to establish a connection -let mut ssh = Ssh::connect("example.com", SshOpts::default()) - .expect("Failed to connect"); - -// Authenticating with the server is a separate step -// 1. You can pass the local handler and authentication and host verification -// will be done over stderr -// 2. You can provide your own handlers for programmatic engagement -ssh.authenticate(LocalSshAuthHandler).await - .expect("Failed to authenticate"); - -// Convert into an ssh client session (no distant server required) -let client = ssh.into_distant_client().await - .expect("Failed to convert into distant client"); -``` - -Below is an example of connecting to an ssh server, spawning a distant server -on the remote machine, and connecting to the distant server: - -```rust -use distant_ssh2::{DistantLaunchOpts, LocalSshAuthHandler, Ssh, SshOpts}; - -// Using default ssh arguments to establish a connection -let mut ssh = Ssh::connect("example.com", SshOpts::default()) - .expect("Failed to connect"); - -// Authenticating with the server is a separate step -// 1. You can pass the local handler and authentication and host verification -// will be done over stderr -// 2. You can provide your own handlers for programmatic engagement -ssh.authenticate(LocalSshAuthHandler).await - .expect("Failed to authenticate"); - -// Convert into a distant session, which involves spawning a distant server -// using the current ssh connection and then establishing a new connection -// to the distant server -// -// This takes in `DistantLaunchOpts` to specify the server's bin path, -// arguments, timeout, and whether or not to spawn using a login shell -let client = ssh.launch_and_connect(DistantLaunchOpts::default()).await - .expect("Failed to spawn server or connect to it"); +distant-ssh2 = "0.20" ``` ## License diff --git a/distant-ssh2/src/lib.rs b/distant-ssh2/src/lib.rs index b50c5f6..7f93a42 100644 --- a/distant-ssh2/src/lib.rs +++ b/distant-ssh2/src/lib.rs @@ -1,3 +1,9 @@ +#![doc = include_str!("../README.md")] + +#[doc = include_str!("../README.md")] +#[cfg(doctest)] +pub struct ReadmeDoctests; + #[cfg(not(any(feature = "libssh", feature = "ssh2")))] compile_error!("Either feature \"libssh\" or \"ssh2\" must be enabled for this crate."); diff --git a/src/lib.rs b/src/lib.rs index 5f7ebdf..ad5846d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,9 @@ +#![doc = include_str!("../README.md")] + +#[doc = include_str!("../README.md")] +#[cfg(doctest)] +pub struct ReadmeDoctests; + use std::process::{ExitCode, Termination}; use derive_more::{Display, Error, From};