Merge pull request servo#53 from servo/rustdoc

Have Travis CI upload rustdoc-generated documentation to GitHub Pages.

Author: SimonSapin

.gitignore

@@ -9,3 +9,4 @@
 *-test
 Makefile
 /target
+/doc

.travis.yml

@@ -8,5 +8,18 @@ install:
   - sudo ./cargo-nightly/install.sh
 
 script:
-  - cargo build --verbose
-  - cargo test --verbose
+  - cargo build
+  - cargo test
+  - rustdoc lib.rs -L target/deps
+
+after_success: |
+  [ $TRAVIS_BRANCH = master ] &&
+  [ $TRAVIS_PULL_REQUEST = false ] &&
+  echo '<meta http-equiv=refresh content=0;url=cssparser/index.html>' > doc/index.html &&
+  sudo pip install ghp-import &&
+  ghp-import -n doc &&
+  git push -fq https://${TOKEN}@github.com/${TRAVIS_REPO_SLUG}.git gh-pages
+
+env:
+  - secure: TDTC2q5Trv22R1pXcMyi2mWToc201aJpCJgLlnwNzkT2bjpQj+0KQvBpI1gIoeQvSL9ud85187C0tdmR7zQmZjBt6mnNCs7EM7QDIPcUcrH0vz8v/RQ+VNxhRAeCwUP4uLEHtnvbi9Q0KXCI1cQivZuMspxVMwvajx/ylcPwb4k=
+

Makefile.in

@@ -7,6 +7,9 @@ AR ?= ar
 RUSTC ?= rustc
 RUSTFLAGS ?=
 EXT_DEPS ?=
+RUSTDOC ?= rustdoc
+RUSTDOC_FLAGS ?=
+RUSTDOC_TARGET ?= doc
 
 RUST_SRC=$(shell find $(VPATH)/. -type f -name '*.rs')
 
@@ -28,6 +31,12 @@ check: cssparser-test
 check-debug: cssparser-tests
 	echo -e "start\n break upcall_fail\n continue\n where\n continue" | gdb -q ./cssparser-tests
 
+.PHONY: doc
+doc: $(RUSTDOC_TARGET)/cssparser/index.html
+
+$(RUSTDOC_TARGET)/cssparser/index.html: lib.rs $(RUST_SRC) $(EXT_DEPS)
+	$(RUSTDOC) $(RUSTDOC_FLAGS) $< -o $(RUSTDOC_TARGET)
+
 .PHONY: clean
 clean:
 	rm -f *.o *.a *.so *.dylib *.rlib *.dll *.dummy *-test

from_bytes.rs

@@ -14,22 +14,16 @@ use parser::{parse_stylesheet_rules, StylesheetParser};
 
 /// Determine the character encoding of a CSS stylesheet and decode it.
 ///
-/// This is based on the presence of a :abbr:`BOM (Byte Order Mark)`,
-/// an `@charset` rule,
-/// and encoding meta-information.
+/// This is based on the presence of a BOM (Byte Order Mark), an `@charset` rule, and
+/// encoding meta-information.
 ///
-/// :param css_bytes: A byte string.
-/// :param protocol_encoding:
-///     The encoding label, if any, defined by HTTP or equivalent protocol.
+/// * `css_bytes`: A byte string.
+/// * `protocol_encoding`: The encoding label, if any, defined by HTTP or equivalent protocol.
 ///     (e.g. via the `charset` parameter of the `Content-Type` header.)
-/// :param environment_encoding:
-///     An optional `Encoding` object
-///     for the `environment encoding
-///     <http://www.w3.org/TR/css-syntax/#environment-encoding>`_,
-///     if any.
-/// :returns:
-///     A 2-tuple of a decoded Unicode string
-///     and the `Encoding` object that was used.
+/// * `environment_encoding`: An optional `Encoding` object for the [environment encoding]
+///     (http://www.w3.org/TR/css-syntax/#environment-encoding), if any.
+///
+/// Returns a 2-tuple of a decoded Unicode string and the `Encoding` object that was used.
 pub fn decode_stylesheet_bytes(css: &[u8], protocol_encoding_label: Option<&str>,
                                environment_encoding: Option<EncodingRef>)
                             -> (String, EncodingRef) {
@@ -78,18 +72,14 @@ fn decode_replace(input: &[u8], fallback_encoding: EncodingRef)-> (String, Encod
 
 /// Parse stylesheet from bytes.
 ///
-/// :param css_bytes: A byte string.
-/// :param protocol_encoding:
-///     The encoding label, if any, defined by HTTP or equivalent protocol.
+/// * `css_bytes`: A byte string.
+/// * `protocol_encoding`: The encoding label, if any, defined by HTTP or equivalent protocol.
 ///     (e.g. via the `charset` parameter of the `Content-Type` header.)
-/// :param environment_encoding:
-///     An optional `Encoding` object
-///     for the `environment encoding
-///     <http://www.w3.org/TR/css-syntax/#environment-encoding>`_,
-///     if any.
-/// :returns:
-///     A 2-tuple of a Iterator<Result<Rule, SyntaxError>>
-///     and the `Encoding` object that was used.
+/// * `environment_encoding`: An optional `Encoding` object for the [environment encoding]
+///     (http://www.w3.org/TR/css-syntax/#environment-encoding), if any.
+///
+/// Returns a 2-tuple of a `Iterator<Result<Rule, SyntaxError>>`
+/// and the `Encoding` object that was used.
 pub fn parse_stylesheet_rules_from_bytes(
         css_bytes: &[u8], protocol_encoding_label: Option<&str>,
         environment_encoding: Option<EncodingRef>)

parser.rs

@@ -4,7 +4,7 @@
 
 // http://dev.w3.org/csswg/css-syntax/#parsing
 
-/// The input to these functions needs to implement Iterator<(ComponentValue, SourceLocation)>.
+/// The input to these functions needs to implement `Iterator<(ComponentValue, SourceLocation)>`.
 /// The input is consumed to avoid doing a lot of copying.
 /// A conforming input can be obtained:
 ///
@@ -25,15 +25,15 @@ pub struct RuleListParser<T>{ iter: T }
 pub struct DeclarationListParser<T>{ iter: T }
 
 /// Parse top-level of a CSS stylesheet.
-/// Return a Iterator<Result<Rule, SyntaxError>>
+/// Return a `Iterator<Result<Rule, SyntaxError>>`
 #[inline]
 pub fn parse_stylesheet_rules<T: Iterator<Node>>(iter: T) -> StylesheetParser<T> {
     StylesheetParser{ iter: iter }
 }
 
 
 /// Parse a non-top level list of rules eg. the content of an @media rule.
-/// Return a Iterator<Result<Rule, SyntaxError>>
+/// Return a `Iterator<Result<Rule, SyntaxError>>`
 #[inline]
 pub fn parse_rule_list<T: Iterator<Node>>(iter: T) -> RuleListParser<T> {
     RuleListParser{ iter: iter }
@@ -42,7 +42,7 @@ pub fn parse_rule_list<T: Iterator<Node>>(iter: T) -> RuleListParser<T> {
 
 /// Parse a list of declarations and at-rules,
 /// like @page in CSS 2.1, all declaration lists in level 3
-/// Return a Iterator<Result<DeclarationListItem, SyntaxError>>
+/// Return a `Iterator<Result<DeclarationListItem, SyntaxError>>`
 #[inline]
 pub fn parse_declaration_list<T: Iterator<Node>>(iter: T) -> DeclarationListParser<T> {
     DeclarationListParser{ iter: iter }

tokenizer.rs

@@ -10,7 +10,7 @@ use std::ascii::StrAsciiExt;
 use ast::*;
 
 
-/// Returns a Iterator<(ComponentValue, SourceLocation)>
+/// Returns a `Iterator<(ComponentValue, SourceLocation)>`
 pub fn tokenize(input: &str) -> Tokenizer {
     let input = preprocess(input);
     Tokenizer {