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
  63     if args.iter().any(|x| "-h" == *x) || args.iter().any(|x| "--help" == *x) {
  64         config::usage();
  65         return;
  66     }
  67
  68     let config = match config::parse_config(args) {
  69       Ok(config) => config,
  70       Err(err) => {
  71         printfln!("error: %s", err);
  72         return;
  73       }
  74     };
  75
  76     run(config);
  77 }
  78
  79 /// Runs rustdoc over the given file
  80 fn run(config: Config) {
  81
  82     let source_file = config.input_crate.clone();
  83
  84     // Create an AST service from the source code
  85     do astsrv::from_file(source_file.to_str()) |srv| {
  86
  87         // Just time how long it takes for the AST to become available
  88         do time(~"wait_ast") {
  89             do astsrv::exec(srv.clone()) |_ctxt| { }
  90         };
  91
  92         // Extract the initial doc tree from the AST. This contains
  93         // just names and node ids.
  94         let doc = time(~"extract", || {
  95             let default_name = source_file.clone();
  96             extract::from_srv(srv.clone(), default_name.to_str())
  97         });
  98
  99         // Refine and publish the document
 100         pass::run_passes(srv, doc, ~[
 101             // Generate type and signature strings
 102             tystr_pass::mk_pass(),
 103             // Record the full paths to various nodes
 104             path_pass::mk_pass(),
 105             // Extract the docs attributes and attach them to doc nodes
 106             attr_pass::mk_pass(),
 107             // Perform various text escaping
 108             escape_pass::mk_pass(),
 109             // Remove things marked doc(hidden)
 110             prune_hidden_pass::mk_pass(),
 111             // Remove things that are private
 112             prune_private_pass::mk_pass(),
 113             // Extract brief documentation from the full descriptions
 114             desc_to_brief_pass::mk_pass(),
 115             // Massage the text to remove extra indentation
 116             unindent_pass::mk_pass(),
 117             // Split text into multiple sections according to headers
 118             sectionalize_pass::mk_pass(),
 119             // Trim extra spaces from text
 120             trim_pass::mk_pass(),
 121             // Sort items by name
 122             sort_item_name_pass::mk_pass(),
 123             // Sort items again by kind
 124             sort_item_type_pass::mk_pass(),
 125             // Create indexes appropriate for markdown
 126             markdown_index_pass::mk_pass(config.clone()),
 127             // Break the document into pages if required by the
 128             // output format
 129             page_pass::mk_pass(config.output_style),
 130             // Render
 131             markdown_pass::mk_pass(
 132                 markdown_writer::make_writer_factory(config.clone())
 133             )
 134         ]);
 135     }
 136 }
 137
 138 pub fn time<T>(what: ~str, f: &fn() -> T) -> T {
 139     let start = extra::time::precise_time_s();
 140     let rv = f();
 141     let end = extra::time::precise_time_s();
 142     info!("time: %3.3f s    %s", end - start, what);
 143     rv
 144 }