Add mathematics support to rustdoc

src/libcollections/dlist.rs

@@ -132,15 +132,15 @@ fn link_with_prev<T>(mut next: Box<Node<T>>, prev: Rawlink<Node<T>>)
 impl<T> Collection for DList<T> {
     /// Returns `true` if the `DList` is empty.
     ///
-    /// This operation should compute in O(1) time.
+    /// This operation should compute in $$O(1)$$ time.
     #[inline]
     fn is_empty(&self) -> bool {
         self.list_head.is_none()
     }
 
     /// Returns the length of the `DList`.
     ///
-    /// This operation should compute in O(1) time.
+    /// This operation should compute in $$O(1)$$ time.
     #[inline]
     fn len(&self) -> uint {
         self.length
@@ -248,15 +248,15 @@ impl<T> Deque<T> for DList<T> {
 
     /// Adds an element first in the list.
     ///
-    /// This operation should compute in O(1) time.
+    /// This operation should compute in $$O(1)$$ time.
     fn push_front(&mut self, elt: T) {
         self.push_front_node(box Node::new(elt))
     }
 
     /// Removes the first element and returns it, or `None` if the list is
     /// empty.
     ///
-    /// This operation should compute in O(1) time.
+    /// This operation should compute in $$O(1)$$ time.
     fn pop_front(&mut self) -> Option<T> {
         self.pop_front_node().map(|box Node{value, ..}| value)
     }
@@ -339,7 +339,7 @@ impl<T> DList<T> {
 
     /// Adds all elements from `other` to the end of the list.
     ///
-    /// This operation should compute in O(1) time.
+    /// This operation should compute in $$O(1)$$ time.
     ///
     /// # Example
     ///
@@ -380,7 +380,7 @@ impl<T> DList<T> {
 
     /// Adds all elements from `other` to the beginning of the list.
     ///
-    /// This operation should compute in O(1) time.
+    /// This operation should compute in $$O(1)$$ time.
     ///
     /// # Example
     ///
@@ -409,7 +409,7 @@ impl<T> DList<T> {
     /// Inserts `elt` before the first `x` in the list where `f(x, elt)` is
     /// true, or at the end.
     ///
-    /// This operation should compute in O(N) time.
+    /// This operation should compute in $$O(N)$$ time.
     ///
     /// # Example
     ///
@@ -448,7 +448,7 @@ impl<T> DList<T> {
     /// Iterates both `DList`s with `a` from self and `b` from `other`, and
     /// put `a` in the result if `f(a, b)` is true, and otherwise `b`.
     ///
-    /// This operation should compute in O(max(N, M)) time.
+    /// This operation should compute in $$O(\max(N, M))$$ time.
     pub fn merge(&mut self, mut other: DList<T>, f: |&T, &T| -> bool) {
         {
             let mut it = self.iter_mut();
@@ -512,7 +512,7 @@ impl<T> DList<T> {
 impl<T: Ord> DList<T> {
     /// Inserts `elt` sorted in ascending order.
     ///
-    /// This operation should compute in O(N) time.
+    /// This operation should compute in $$O(N)$$ time.
     #[inline]
     pub fn insert_ordered(&mut self, elt: T) {
         self.insert_when(elt, |a, b| a >= b)

src/libcollections/lib.rs

@@ -17,7 +17,8 @@
 #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
        html_favicon_url = "http://www.rust-lang.org/favicon.ico",
        html_root_url = "http://doc.rust-lang.org/master/",
-       html_playground_url = "http://play.rust-lang.org/")]
+       html_playground_url = "http://play.rust-lang.org/",
+       enable_math)]
 
 #![feature(macro_rules, managed_boxes, default_type_params, phase, globs)]
 #![feature(unsafe_destructor, import_shadowing)]

src/libcollections/priority_queue.rs

@@ -10,10 +10,10 @@
 
 //! A priority queue implemented with a binary heap.
 //!
-//! Insertions have `O(log n)` time complexity and checking or popping the largest element is
-//! `O(1)`. Converting a vector to a priority queue can be done in-place, and has `O(n)`
+//! Insertions have $$O(\log n)$$ time complexity and checking or popping the largest element is
+//! $$O(1)$$ . Converting a vector to a priority queue can be done in-place, and has $$O(n)$$
 //! complexity. A priority queue can also be converted to a sorted vector in-place, allowing it to
-//! be used for an `O(n log n)` in-place heapsort.
+//! be used for an $$O(n \log n)$$ in-place heapsort.
 //!
 //! # Example
 //!

src/libcollections/ringbuf.rs

@@ -8,8 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! This crate implements a double-ended queue with `O(1)` amortized inserts and removals from both
-//! ends of the container. It also has `O(1)` indexing like a vector. The contained elements are
+//! This crate implements a double-ended queue with $$O(1)$$ amortized inserts and removals from both
+//! ends of the container. It also has $$O(1)$$ indexing like a vector. The contained elements are
 //! not required to be copyable, and the queue will be sendable if the contained type is sendable.
 //! Its interface `Deque` is defined in `collections`.
 

src/libcollections/slice.rs

@@ -562,7 +562,7 @@ pub trait MutableSliceAllocating<'a, T> {
     /// Sorts the slice, in place, using `compare` to compare
     /// elements.
     ///
-    /// This sort is `O(n log n)` worst-case and stable, but allocates
+    /// This sort is $$O(n \log n)$$ worst-case and stable, but allocates
     /// approximately `2 * n`, where `n` is the length of `self`.
     ///
     /// # Example

src/libcollections/smallintmap.rs

@@ -9,7 +9,7 @@
 // except according to those terms.
 
 //! A simple map based on a vector for small integer keys. Space requirements
-//! are O(highest integer key).
+//! are $$O(\text{highest integer key})$$.
 
 #![allow(missing_doc)]
 

src/libcollections/string.rs

@@ -746,7 +746,7 @@ impl String {
     ///
     /// # Warning
     ///
-    /// This is a O(n) operation as it requires copying every element in the
+    /// This is a $$O(n)$$ operation as it requires copying every element in the
     /// buffer.
     ///
     /// # Failure

src/libcollections/vec.rs

@@ -10,7 +10,7 @@
 
 //! A growable list type, written `Vec<T>` but pronounced 'vector.'
 //!
-//! Vectors have `O(1)` indexing, push (to the end) and pop (from the end).
+//! Vectors have $$O(1)$$ indexing, push (to the end) and pop (from the end).
 
 use core::prelude::*;
 
@@ -897,8 +897,8 @@ impl<T> Vec<T> {
 
     /// Sorts the vector, in place, using `compare` to compare elements.
     ///
-    /// This sort is `O(n log n)` worst-case and stable, but allocates
-    /// approximately `2 * n`, where `n` is the length of `self`.
+    /// This sort is $$O(n \log n)$$ worst-case and stable, but allocates
+    /// approximately `2 * n` elements, where `n` is the length of `self`.
     ///
     /// # Example
     ///
@@ -1006,7 +1006,7 @@ impl<T> Vec<T> {
     }
 
     /// Removes an element from anywhere in the vector and return it, replacing
-    /// it with the last element. This does not preserve ordering, but is O(1).
+    /// it with the last element. This does not preserve ordering, but is $$O(1)$$ .
     ///
     /// Returns `None` if `index` is out of bounds.
     ///
@@ -1039,7 +1039,7 @@ impl<T> Vec<T> {
     ///
     /// # Warning
     ///
-    /// This is an O(n) operation as it requires copying every element in the
+    /// This is an $$O(n)$$ operation as it requires copying every element in the
     /// vector.
     ///
     /// # Example
@@ -1060,7 +1060,7 @@ impl<T> Vec<T> {
     ///
     /// # Warning
     ///
-    /// This is an O(n) operation as it requires copying every element in the
+    /// This is an $$O(n)$$ operation as it requires copying every element in the
     /// vector.
     ///
     /// # Example
@@ -1464,7 +1464,7 @@ impl<T> Vec<T> {
 impl<T:Ord> Vec<T> {
     /// Sorts the vector in place.
     ///
-    /// This sort is `O(n log n)` worst-case and stable, but allocates
+    /// This sort is $$O(n \log n)$$ worst-case and stable, but allocates
     /// approximately `2 * n`, where `n` is the length of `self`.
     ///
     /// # Example

src/librand/distributions/exponential.rs

@@ -17,9 +17,7 @@ use distributions::{ziggurat, ziggurat_tables, Sample, IndependentSample};
 
 /// A wrapper around an `f64` to generate Exp(1) random numbers.
 ///
-/// See `Exp` for the general exponential distribution.Note that this
- // has to be unwrapped before use as an `f64` (using either
-/// `*` or `mem::transmute` is safe).
+/// See `Exp` for the general exponential distribution.
 ///
 /// Implemented via the ZIGNOR variant[1] of the Ziggurat method. The
 /// exact description in the paper was adjusted to use tables for the
@@ -53,8 +51,8 @@ impl Rand for Exp1 {
 
 /// The exponential distribution `Exp(lambda)`.
 ///
-/// This distribution has density function: `f(x) = lambda *
-/// exp(-lambda * x)` for `x > 0`.
+/// This distribution has density function: $$f(x) = \lambda
+/// e^{-\lambda x}$$ for $$x > 0$$ .
 ///
 /// # Example
 ///

src/librand/distributions/gamma.rs

@@ -22,12 +22,11 @@ use super::{IndependentSample, Sample, Exp};
 ///
 /// The density function of this distribution is
 ///
-/// ```text
-/// f(x) =  x^(k - 1) * exp(-x / θ) / (Γ(k) * θ^k)
-/// ```
+/// $$f(x) =  x^{k - 1} \frac{\exp(-x / \theta)}{\Gamma(k) \theta^k}$$
 ///
-/// where `Γ` is the Gamma function, `k` is the shape and `θ` is the
-/// scale and both `k` and `θ` are strictly positive.
+/// where $$\Gamma$$ is the Gamma function, $$k$$ is the shape and
+/// $$\theta$$ is the scale and both $$k$$ and $$\theta$$ are strictly
+/// positive.
 ///
 /// The algorithm used is that described by Marsaglia & Tsang 2000[1],
 /// falling back to directly sampling from an Exponential for `shape

src/librand/lib.rs

@@ -22,7 +22,8 @@
 #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk.png",
        html_favicon_url = "http://www.rust-lang.org/favicon.ico",
        html_root_url = "http://doc.rust-lang.org/master/",
-       html_playground_url = "http://play.rust-lang.org/")]
+       html_playground_url = "http://play.rust-lang.org/",
+       enable_math)]
 
 #![feature(macro_rules, phase, globs)]
 #![no_std]

src/librustdoc/html/layout.rs

@@ -12,6 +12,7 @@ use std::fmt;
 use std::io;
 
 use externalfiles::ExternalHtml;
+use html::markdown;
 
 #[deriving(Clone)]
 pub struct Layout {
@@ -20,6 +21,7 @@ pub struct Layout {
     pub external_html: ExternalHtml,
     pub krate: String,
     pub playground_url: String,
+    pub enable_math: bool,
 }
 
 pub struct Page<'a> {
@@ -34,7 +36,11 @@ pub fn render<T: fmt::Show, S: fmt::Show>(
     dst: &mut io::Writer, layout: &Layout, page: &Page, sidebar: &S, t: &T)
     -> io::IoResult<()>
 {
-    write!(dst,
+    // Reset state on whether we've seen math, so as to avoid loading mathjax
+    // on pages that don't actually *have* math.
+    markdown::math_seen.replace(Some(false));
+
+    try!(write!(dst,
 r##"<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -47,6 +53,7 @@ r##"<!DOCTYPE html>
     <title>{title}</title>
 
     <link rel="stylesheet" type="text/css" href="{root_path}main.css">
+    {katex_css}
 
     {favicon}
     {in_header}
@@ -119,13 +126,13 @@ r##"<!DOCTYPE html>
         window.rootPath = "{root_path}";
         window.currentCrate = "{krate}";
         window.playgroundUrl = "{play_url}";
+        window.useKaTeX = true;
     </script>
     <script src="{root_path}jquery.js"></script>
     <script src="{root_path}main.js"></script>
     {play_js}
     <script async src="{root_path}search-index.js"></script>
-</body>
-</html>"##,
+"##,
     content   = *t,
     root_path = page.root_path,
     ty        = page.ty,
@@ -156,7 +163,27 @@ r##"<!DOCTYPE html>
     } else {
         format!(r#"<script src="{}playpen.js"></script>"#, page.root_path)
     },
-    )
+    katex_css = if layout.enable_math {
+        // this is inserted even for pages for which there is no
+        // actual mathematics (unlike the JS), but this CSS is quite
+        // small, and it's harder to insert this conditionally, since
+        // that would require rendering the whole thing into memory
+        // and then printing this, and only then print the
+        // markdown.
+        format!(r#"<link rel="stylesheet" type="text/css" href="{}katex/katex.min.css">"#,
+                page.root_path)
+    } else {
+        "".to_string()
+    },
+    ));
+
+    // This must be done after everything is rendered, so that
+    // `math_seen` captures all possible $$'s on this page.
+    if layout.enable_math && markdown::math_seen.get().map_or(false, |x| *x) {
+        try!(write!(dst, "<script src=\"{}katex/katex.min.js\"></script>", page.root_path));
+    }
+
+    dst.write_str("</body>\n</html>")
 }
 
 pub fn redirect(dst: &mut io::Writer, url: &str) -> io::IoResult<()> {