Improve documentation.

Mainly get rid of some very old workarounds for limitations
in early cargo doc.

src/Template_syntax.rs

@@ -55,14 +55,14 @@
 //!
 //! The curly brackets, `{` and `}`, is used for blocks (see Loops,
 //! Conditionals, and Calling other templates below).
-
+//!
 //! To use verbatim curly brackets in the template body, they must be
 //! escaped as `@{` and `@}`, the same goes for the `@` sign, that
 //! precedes expressions and special blocks; verbtim `@` signs must be
 //! escaped as `@@`.
 //!
-//! [`ToHtml`]: ../templates/trait.ToHtml.html
-//! [`Display`]: https://doc.rust-lang.org/std/fmt/trait.Display.html
+//! [`ToHtml`]: crate::templates::ToHtml
+//! [`Display`]: std::fmt::Display
 #![allow(non_snake_case)]
 
 pub mod a_Value_expressions {

src/lib.rs

@@ -14,7 +14,7 @@
 //!
 //! The template syntax, which is inspired by [Twirl], the Scala-based
 //! template engine in [Play framework], is documented in
-//! [the _Template syntax_ module].
+//! the [Template_syntax] module.
 //! A sample template may look like this:
 //!
 //! ```html
@@ -45,7 +45,6 @@
 //!
 //! [Twirl]: https://github.com/playframework/twirl
 //! [Play framework]: https://www.playframework.com/
-//! [the _Template syntax_ module]: Template_syntax/index.html
 //! [examples in the repository]: https://github.com/kaj/ructe/tree/master/examples
 //! [using ructe with warp and diesel]: https://github.com/kaj/warp-diesel-ructe-sample
 //!
@@ -54,8 +53,6 @@
 //! A minimal such build script looks like the following.
 //! See the [`Ructe`] struct documentation for details.
 //!
-//! [`Ructe`]: struct.Ructe.html
-//!
 //! ```rust,no_run
 //! use ructe::{Result, Ructe};
 //!
@@ -89,8 +86,8 @@
 //!   version 0.3.x of the [mime] crate.
 //! * `mime02` -- Static files know their mime types, compatible with
 //!   version 0.2.x of the [mime] crate.
-//! * `warp03` -- Provide an extension to [`Response::Builder`] to
-//!   simplify template rendering in the [warp] framework, versions 0.3.x.
+//! * `warp03` -- Provide an extension to `Response::Builder` of the [warp]
+//!   framework (versions 0.3.x) to simplify template rendering.
 //! * `http-types` -- Static files know their mime types, compatible with
 //!   the [http-types] crate.
 //! * `tide013`, `tide014`, `tide015`, `tide016` -- Support for the
@@ -101,7 +98,6 @@
 //!   are actually just aliases for the first one, but a future tide
 //!   version may require a modified feature.)
 //!
-//! [`response::Builder`]: ../http/response/struct.Builder.html
 //! [mime]: https://crates.rs/crates/mime
 //! [warp]: https://crates.rs/crates/warp
 //! [tide]: https://crates.rs/crates/tide
@@ -218,10 +214,9 @@ impl Ructe {
     /// `out_dir`.
     ///
     /// If you are using Ructe in a project that uses [cargo],
-    /// you should probably use [`from_env`] instead.
+    /// you should probably use [`Ructe::from_env`] instead.
     ///
     /// [cargo]: https://doc.rust-lang.org/cargo/
-    /// [`from_env`]: #method.from_env
     pub fn new(outdir: PathBuf) -> Result<Ructe> {
         let mut f = Vec::with_capacity(512);
         let outdir = outdir.join("templates");
@@ -300,8 +295,7 @@ impl Ructe {
     /// `templates::statics::logo_png` as a [`StaticFile`] in your
     /// project.
     ///
-    /// [`StaticFiles`]: struct.StaticFiles.html
-    /// [`StaticFile`]: templates/struct.StaticFile.html
+    /// [`StaticFile`]: templates::StaticFile
     pub fn statics(&mut self) -> Result<StaticFiles> {
         self.f.write_all(b"pub mod statics;")?;
         StaticFiles::for_template_dir(
@@ -461,6 +455,4 @@ impl From<rsass::Error> for RucteError {
 }
 
 /// A result where the error type is a [`RucteError`].
-///
-/// [`RucteError`]: enum.RucteError.html
 pub type Result<T> = std::result::Result<T, RucteError>;

src/templates/utils_warp03.rs

@@ -1,7 +1,7 @@
 use mime::TEXT_HTML_UTF_8;
 use std::error::Error;
 use std::io;
-use warp::http::{header::CONTENT_TYPE, response::Builder};
+use warp::http::{header::CONTENT_TYPE, response};
 use warp::{reject::Reject, reply::Response, Reply};
 
 /// Extension trait for [`response::Builder`] to simplify template rendering.
@@ -18,10 +18,12 @@ use warp::{reject::Reject, reply::Response, Reply};
 ///
 /// ```
 /// # use std::io::{self, Write};
-/// # use warp::http::Response;
-/// # use ructe::templates::RenderRucte;
+/// use warp::http::Response;
+/// use ructe::templates::RenderRucte;
+///
 /// # fn page(o: &mut Write, _: u8, _: u8) -> io::Result<()> { Ok(()) }
 /// # let (title, body) = (47, 11);
+/// // ... at the end of a handler:
 /// Response::builder().html(|o| page(o, title, body))
 /// # ;
 /// ```
@@ -41,7 +43,8 @@ use warp::{reject::Reject, reply::Response, Reply};
 /// # ;
 /// ```
 ///
-/// [`response::Builder`]: ../../http/response/struct.Builder.html
+/// Note that the `.html` method _finalizes_ the builder, that is, on
+/// success it returns a [`Response`] rather than a [`response::Builder`].
 pub trait RenderRucte {
     /// Render a template on the response builder.
     ///
@@ -51,7 +54,7 @@ pub trait RenderRucte {
         F: FnOnce(&mut Vec<u8>) -> io::Result<()>;
 }
 
-impl RenderRucte for Builder {
+impl RenderRucte for response::Builder {
     fn html<F>(self, f: F) -> Result<Response, RenderError>
     where
         F: FnOnce(&mut Vec<u8>) -> io::Result<()>,