Merge pull request #32 from amousset/improve-doc

Improve documentation

.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:

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=<user@localhost> to=<root@localhost>
+//! ```
+//!
+//! ## 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=<user@localhost> to=<root@localhost>
+//! To: <root@localhost>
+//! From: <user@localhost>
+//! Subject: Hello
+//! Date: Sat, 31 Oct 2015 13:42:19 +0100
+//! Message-ID: <b7c211bc-9811-45ce-8cd9-68eab575d695.lettre@localhost>
+//!
+//! 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]

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,
 }