src/librustdoc/rustdoc.rs

   1 // Copyright 2012-2013 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! Rustdoc - The Rust documentation generator
  12
  13 #[link(name = "rustdoc",
  14        vers = "0.8-pre",
  15        uuid = "f8abd014-b281-484d-a0c3-26e3de8e2412",
  16        url = "https://github.com/mozilla/rust/tree/master/src/rustdoc")];
  17
  18 #[comment = "The Rust documentation generator"];
  19 #[license = "MIT/ASL2"];
  20 #[crate_type = "lib"];
  21
  22 extern mod extra;
  23 extern mod rustc;
  24 extern mod syntax;
  25
  26 use std::os;
  27
  28 use config::Config;
  29 use doc::Item;
  30 use doc::ItemUtils;
  31
  32 pub mod pass;
  33 pub mod config;
  34 pub mod parse;
  35 pub mod extract;
  36 pub mod attr_parser;
  37 pub mod doc;
  38 pub mod markdown_index_pass;
  39 pub mod markdown_pass;
  40 pub mod markdown_writer;
  41 pub mod fold;
  42 pub mod path_pass;
  43 pub mod attr_pass;
  44 pub mod tystr_pass;
  45 pub mod prune_hidden_pass;
  46 pub mod desc_to_brief_pass;
  47 pub mod text_pass;
  48 pub mod unindent_pass;
  49 pub mod trim_pass;
  50 pub mod astsrv;
  51 pub mod demo;
  52 pub mod sort_pass;
  53 pub mod sort_item_name_pass;
  54 pub mod sort_item_type_pass;
  55 pub mod page_pass;
  56 pub mod sectionalize_pass;
  57 pub mod escape_pass;
  58 pub mod prune_private_pass;
  59
  60 pub fn main() {
  61     let args = os::args();
  62     main_args(args);
  63 }
  64
  65 pub fn main_args(args: &[~str]) {
  66     if args.iter().any(|x| "-h" == *x) || args.iter().any(|x| "--help" == *x) {
  67         config::usage();
  68         return;
  69     }
  70
  71     let config = match config::parse_config(args) {
  72       Ok(config) => config,
  73       Err(err) => {
  74         printfln!("error: %s", err);
  75         return;
  76       }
  77     };
  78
  79     run(config);
  80 }
  81
  82 /// Runs rustdoc over the given file
  83 fn run(config: Config) {
  84
  85     let source_file = config.input_crate.clone();
  86
  87     // Create an AST service from the source code
  88     do astsrv::from_file(source_file.to_str()) |srv| {
  89
  90         // Just time how long it takes for the AST to become available
  91         do time(~"wait_ast") {
  92             do astsrv::exec(srv.clone()) |_ctxt| { }
  93         };
  94
  95         // Extract the initial doc tree from the AST. This contains
  96         // just names and node ids.
  97         let doc = time(~"extract", || {
  98             let default_name = source_file.clone();
  99             extract::from_srv(srv.clone(), default_name.to_str())
 100         });
 101
 102         // Refine and publish the document
 103         pass::run_passes(srv, doc, ~[
 104             // Generate type and signature strings
 105             tystr_pass::mk_pass(),
 106             // Record the full paths to various nodes
 107             path_pass::mk_pass(),
 108             // Extract the docs attributes and attach them to doc nodes
 109             attr_pass::mk_pass(),
 110             // Perform various text escaping
 111             escape_pass::mk_pass(),
 112             // Remove things marked doc(hidden)
 113             prune_hidden_pass::mk_pass(),
 114             // Remove things that are private
 115             prune_private_pass::mk_pass(),
 116             // Extract brief documentation from the full descriptions
 117             desc_to_brief_pass::mk_pass(),
 118             // Massage the text to remove extra indentation
 119             unindent_pass::mk_pass(),
 120             // Split text into multiple sections according to headers
 121             sectionalize_pass::mk_pass(),
 122             // Trim extra spaces from text
 123             trim_pass::mk_pass(),
 124             // Sort items by name
 125             sort_item_name_pass::mk_pass(),
 126             // Sort items again by kind
 127             sort_item_type_pass::mk_pass(),
 128             // Create indexes appropriate for markdown
 129             markdown_index_pass::mk_pass(config.clone()),
 130             // Break the document into pages if required by the
 131             // output format
 132             page_pass::mk_pass(config.output_style),
 133             // Render
 134             markdown_pass::mk_pass(
 135                 markdown_writer::make_writer_factory(config.clone())
 136             )
 137         ]);
 138     }
 139 }
 140
 141 pub fn time<T>(what: ~str, f: &fn() -> T) -> T {
 142     let start = extra::time::precise_time_s();
 143     let rv = f();
 144     let end = extra::time::precise_time_s();
 145     info!("time: %3.3f s    %s", end - start, what);
 146     rv
 147 }