From 63afc082629044755df0c416ecf4c20ef0375254 Mon Sep 17 00:00:00 2001 From: zzmp Date: Sat, 28 Jun 2014 03:35:25 -0700 Subject: [PATCH] Allow external html in rustdoc for crates. Updated documentation to reflect md->html. Modularized external file loading. --- man/rustdoc.1 | 9 +++++ mk/docs.mk | 8 ++-- src/doc/rustdoc.md | 19 +++++++-- src/librustdoc/externalfiles.rs | 70 +++++++++++++++++++++++++++++++++ src/librustdoc/html/layout.rs | 11 ++++++ src/librustdoc/html/render.rs | 8 +++- src/librustdoc/lib.rs | 28 +++++++++---- src/librustdoc/markdown.rs | 59 ++++----------------------- 8 files changed, 143 insertions(+), 69 deletions(-) create mode 100644 src/librustdoc/externalfiles.rs diff --git a/man/rustdoc.1 b/man/rustdoc.1 index 82b7ee27b94..d5795c328e7 100644 --- a/man/rustdoc.1 +++ b/man/rustdoc.1 @@ -38,6 +38,15 @@ directory to load plugins from (default: /tmp/rustdoc_ng/plugins) -L --library-path directory to add to crate search path .TP +--html-in-header +file to add to +.TP +--html-before-content +file to add in , before content +.TP +--html-after-content +file to add in , after content +.TP -h, --help Print help diff --git a/mk/docs.mk b/mk/docs.mk index 8098a0682a5..213565b09ac 100644 --- a/mk/docs.mk +++ b/mk/docs.mk @@ -35,16 +35,16 @@ DOCS := index intro tutorial guide guide-ffi guide-macros guide-lifetimes \ PDF_DOCS := tutorial rust RUSTDOC_DEPS_rust := doc/full-toc.inc -RUSTDOC_FLAGS_rust := --markdown-in-header=doc/full-toc.inc +RUSTDOC_FLAGS_rust := --html-in-header=doc/full-toc.inc L10N_LANGS := ja # Generally no need to edit below here. # The options are passed to the documentation generators. -RUSTDOC_HTML_OPTS_NO_CSS = --markdown-before-content=doc/version_info.html \ - --markdown-in-header=doc/favicon.inc \ - --markdown-after-content=doc/footer.inc \ +RUSTDOC_HTML_OPTS_NO_CSS = --html-before-content=doc/version_info.html \ + --html-in-header=doc/favicon.inc \ + --html-after-content=doc/footer.inc \ --markdown-playground-url='http://play.rust-lang.org/' RUSTDOC_HTML_OPTS = $(RUSTDOC_HTML_OPTS_NO_CSS) --markdown-css rust.css diff --git a/src/doc/rustdoc.md b/src/doc/rustdoc.md index 2287bcabff7..8199eaea82c 100644 --- a/src/doc/rustdoc.md +++ b/src/doc/rustdoc.md @@ -103,6 +103,17 @@ rustdoc can also generate JSON, for consumption by other tools, with `rustdoc --output-format json`, and also consume already-generated JSON with `rustdoc --input-format json`. +rustdoc also supports personalizing the output from crates' documentation, +similar to markdown options. + +- `--html-in-header FILE`: includes the contents of `FILE` at the + end of the `...` section. +- `--html-before-content FILE`: includes the contents of `FILE` + directly after ``, before the rendered content (including the + search bar). +- `--html-after-content FILE`: includes the contents of `FILE` + after all the rendered content. + # Using the Documentation The web pages generated by rustdoc present the same logical hierarchy that one @@ -238,16 +249,16 @@ detected by a `.md` or `.markdown` extension. There are 4 options to modify the output that Rustdoc creates. - `--markdown-css PATH`: adds a `` tag pointing to `PATH`. -- `--markdown-in-header FILE`: includes the contents of `FILE` at the +- `--html-in-header FILE`: includes the contents of `FILE` at the end of the `...` section. -- `--markdown-before-content FILE`: includes the contents of `FILE` +- `--html-before-content FILE`: includes the contents of `FILE` directly after ``, before the rendered content (including the title). -- `--markdown-after-content FILE`: includes the contents of `FILE` +- `--html-after-content FILE`: includes the contents of `FILE` directly before ``, after all the rendered content. All of these can be specified multiple times, and they are output in -the order in which they are specified. The first line of the file must +the order in which they are specified. The first line of the file being rendered must be the title, prefixed with `%` (e.g. this page has `% Rust Documentation` on the first line). diff --git a/src/librustdoc/externalfiles.rs b/src/librustdoc/externalfiles.rs new file mode 100644 index 00000000000..0931f132c02 --- /dev/null +++ b/src/librustdoc/externalfiles.rs @@ -0,0 +1,70 @@ +// Copyright 2014 The Rust Project Developers. See the COPYRIGHT +// file at the top-level directory of this distribution and at +// http://rust-lang.org/COPYRIGHT. +// +// Licensed under the Apache License, Version 2.0 or the MIT license +// , at your +// option. This file may not be copied, modified, or distributed +// except according to those terms. + +use std::{io, str}; + +#[deriving(Clone)] +pub struct ExternalHtml{ + pub in_header: String, + pub before_content: String, + pub after_content: String +} + +impl ExternalHtml { + pub fn load(in_header: &[String], before_content: &[String], after_content: &[String]) + -> Option { + match (load_external_files(in_header), + load_external_files(before_content), + load_external_files(after_content)) { + (Some(ih), Some(bc), Some(ac)) => Some(ExternalHtml { + in_header: ih, + before_content: bc, + after_content: ac + }), + _ => None + } + } +} + +pub fn load_string(input: &Path) -> io::IoResult> { + let mut f = try!(io::File::open(input)); + let d = try!(f.read_to_end()); + Ok(str::from_utf8(d.as_slice()).map(|s| s.to_string())) +} + +macro_rules! load_or_return { + ($input: expr, $cant_read: expr, $not_utf8: expr) => { + { + let input = Path::new($input); + match ::externalfiles::load_string(&input) { + Err(e) => { + let _ = writeln!(&mut io::stderr(), + "error reading `{}`: {}", input.display(), e); + return $cant_read; + } + Ok(None) => { + let _ = writeln!(&mut io::stderr(), + "error reading `{}`: not UTF-8", input.display()); + return $not_utf8; + } + Ok(Some(s)) => s + } + } + } +} + +pub fn load_external_files(names: &[String]) -> Option { + let mut out = String::new(); + for name in names.iter() { + out.push_str(load_or_return!(name.as_slice(), None, None).as_slice()); + out.push_char('\n'); + } + Some(out) +} diff --git a/src/librustdoc/html/layout.rs b/src/librustdoc/html/layout.rs index 61a2d3c5d9c..aa298d07780 100644 --- a/src/librustdoc/html/layout.rs +++ b/src/librustdoc/html/layout.rs @@ -11,10 +11,13 @@ use std::fmt; use std::io; +use externalfiles::ExternalHtml; + #[deriving(Clone)] pub struct Layout { pub logo: String, pub favicon: String, + pub external_html: ExternalHtml, pub krate: String, pub playground_url: String, } @@ -44,6 +47,7 @@ pub fn render( {favicon} + {in_header} + {before_content} +