From 489a6e892e6c4e5c46c458b4f6566b7d5a8a7f78 Mon Sep 17 00:00:00 2001 From: Alexis Mousset Date: Sat, 31 Oct 2015 21:23:06 +0100 Subject: [PATCH] Improve documentation --- .travis.yml | 11 ++-- src/lib.rs | 111 ++++++++++++++++++++++++++------------ src/transport/file/mod.rs | 5 +- 3 files changed, 88 insertions(+), 39 deletions(-) diff --git a/.travis.yml b/.travis.yml index c47e7c9..8ab3c3a 100644 --- a/.travis.yml +++ b/.travis.yml @@ -16,7 +16,7 @@ cache: - target/release/deps - target/release/build -install: pip install 'travis-cargo<0.2' --user && export PATH=$HOME/.local/bin:$PATH +install: pip install 'ghp-import' 'travis-cargo<0.2' --user && export PATH=$HOME/.local/bin:$PATH addons: apt: @@ -32,12 +32,17 @@ before_script: script: - travis-cargo build - travis-cargo test - - travis-cargo doc after_success: - travis-cargo --only nightly bench - - travis-cargo --only stable doc-upload - travis-cargo --only stable coveralls --no-sudo + - [ $TRAVIS_BRANCH = master ] && + [ $TRAVIS_PULL_REQUEST = false ] && + [ $TRAVIS_RUST_VERSION = stable ] && + cargo doc --no-deps && + ghp-import -n target/doc && + git push -fq https://${TOKEN}@github.com/lettre/lettre.github.io.git master + env: global: diff --git a/src/lib.rs b/src/lib.rs index 0a03be8..c66936f 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,6 +1,80 @@ -//! # Rust email client +//! Lettre is a mailer written in Rust. It provides a simple email builder and several transports. //! -//! This client should tend to follow [RFC +//! ## Architecture +//! +//! This mailer is divided into: +//! +//! * An `email` part: builds the email message +//! * A `transport` part: contains the available transports for your emails. To be sendable, the emails have to implement `SendableEmail`. +//! +//! ## Stub transport +//! +//! The stub transport only logs message envelope and drops the content. It can be useful for testing purposes. +//! +//! ```rust +//! use lettre::transport::stub::StubEmailTransport; +//! use lettre::transport::EmailTransport; +//! use lettre::email::EmailBuilder; +//! +//! let mut sender = StubEmailTransport; +//! let email = EmailBuilder::new() +//! .to("root@localhost") +//! .from("user@localhost") +//! .body("Hello World!") +//! .subject("Hello") +//! .build() +//! .unwrap(); +//! let result = sender.send(email); +//! assert!(result.is_ok()); +//! ``` +//! +//! Will log the line: +//! +//! ```text +//! b7c211bc-9811-45ce-8cd9-68eab575d695: from= to= +//! ``` +//! +//! ## File transport +//! +//! The file transport writes the emails to the given directory. The name of the file will be `message_id.txt`. +//! It can be useful for testing purposes. +//! +//! ```rust +//! use std::env::temp_dir; +//! +//! use lettre::transport::file::FileEmailTransport; +//! use lettre::transport::EmailTransport; +//! use lettre::email::{EmailBuilder, SendableEmail}; +//! +//! // Write to the local temp directory +//! let mut sender = FileEmailTransport::new(temp_dir()); +//! let email = EmailBuilder::new() +//! .to("root@localhost") +//! .from("user@localhost") +//! .body("Hello World!") +//! .subject("Hello") +//! .build() +//! .unwrap(); +//! +//! let result = sender.send(email); +//! assert!(result.is_ok()); +//! ``` +//! Example result in `/tmp/b7c211bc-9811-45ce-8cd9-68eab575d695.txt`: +//! +//! ```text +//! b7c211bc-9811-45ce-8cd9-68eab575d695: from= to= +//! To: +//! From: +//! Subject: Hello +//! Date: Sat, 31 Oct 2015 13:42:19 +0100 +//! Message-ID: +//! +//! Hello World! +//! ``` +//! +//! ## SMTP transport +//! +//! This SMTP follows [RFC //! 5321](https://tools.ietf.org/html/rfc5321), but is still //! a work in progress. It is designed to efficiently send emails from an //! application to a @@ -16,16 +90,6 @@ //! * STARTTLS ([RFC 2487](http://tools.ietf.org/html/rfc2487)) //! * SMTPUTF8 ([RFC 6531](http://tools.ietf.org/html/rfc6531)) //! -//! ## Architecture -//! -//! This client is divided into three main parts: -//! -//! * transport: a low level SMTP client providing all SMTP commands -//! * mailer: a high level SMTP client providing an easy method to send emails -//! * email: generates the email to be sent with the sender -//! -//! ## Usage -//! //! ### Simple example //! //! This is the most basic example of usage: @@ -105,28 +169,6 @@ //! mailer.close(); //! ``` //! -//! ### Using the client directly -//! -//! If you just want to send an email without using `Email` to provide headers: -//! -//! ```rust -//! use lettre::email::SimpleSendableEmail; -//! use lettre::transport::smtp::{SmtpTransport, SmtpTransportBuilder}; -//! use lettre::transport::EmailTransport; -//! -//! // Create a minimal email -//! let email = SimpleSendableEmail::new( -//! "test@example.com", -//! "test@example.org", -//! "Hello world !" -//! ); -//! -//! let mut mailer = -//! SmtpTransportBuilder::localhost().unwrap().build(); -//! let result = mailer.send(email); -//! assert!(result.is_ok()); -//! ``` -//! //! ### Lower level //! //! You can also send commands, here is a simple email transaction without @@ -147,6 +189,7 @@ //! let _ = email_client.quit(); //! ``` + #![deny(missing_docs, unsafe_code, unstable_features)] #[macro_use] diff --git a/src/transport/file/mod.rs b/src/transport/file/mod.rs index a33f6ac..fe3da5a 100644 --- a/src/transport/file/mod.rs +++ b/src/transport/file/mod.rs @@ -1,4 +1,5 @@ -//! TODO +//! This transport creates a file for each email, containing the enveloppe information and the email +//! itself. use std::path::{Path, PathBuf}; use std::io::prelude::*; @@ -10,7 +11,7 @@ use transport::smtp::response::Response; use transport::smtp::response::{Category, Code, Severity}; use email::SendableEmail; -/// TODO +/// Writes the content and the enveloppe information to a file pub struct FileEmailTransport { path: PathBuf, }