bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

rustdoc: Add anchors to section headers

Browse source 
This commit adds a appear-on-over link to all section headers to generated
documentation. Each header also receives an id now, even those generated through
markdown. The purpose of this is to provide easy to link to sections.

This modifies the default header markdown generation because the default id
added looks like "toc_NN" which is difficult to reconcile among all sections (by
default each section gets a "toc_0" id), and it's also not very descriptive of
where you're going.

This chooses to adopt the github-style anchors by taking the contents of the
title and hyphen-separating them (after lower casing).

Closes #12681
This commit is contained in:
Alex Crichton 2014-03-04 11:24:20 -08:00
parent 0a5138c752
commit 31e7e676e1
4 changed files with 105 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

75
src/librustdoc/html/markdown.rs
View file

@ -28,14 +28,17 @@
use std::cast;
use std::fmt;
use std::intrinsics;
use std::io;
use std::libc;
use std::local_data;
use std::mem;
use std::str;
use std::intrinsics;
use std::vec;
use collections::HashMap;
use html::highlight;
use html::escape::Escape;
/// A unit struct which has the `fmt::Show` trait implemented. When
/// formatted, this struct will emit the HTML corresponding to the rendered
@ -52,8 +55,11 @@ static MKDEXT_STRIKETHROUGH: libc::c_uint = 1 << 4;
type sd_markdown = libc::c_void; // this is opaque to us
struct sd_callbacks {
blockcode: extern "C" fn(*buf, *buf, *buf, *libc::c_void),
other: [libc::size_t, ..25],
blockcode: Option<extern "C" fn(*buf, *buf, *buf, *libc::c_void)>,
blockquote: Option<extern "C" fn(*buf, *buf, *libc::c_void)>,
blockhtml: Option<extern "C" fn(*buf, *buf, *libc::c_void)>,
header: Option<extern "C" fn(*buf, *buf, libc::c_int, *libc::c_void)>,
other: [libc::size_t, ..22],
}
struct html_toc_data {
@ -115,6 +121,8 @@ fn stripped_filtered_line<'a>(s: &'a str) -> Option<&'a str> {
}
}
local_data_key!(used_header_map: HashMap<~str, uint>)
pub fn render(w: &mut io::Writer, s: &str) -> fmt::Result {
extern fn block(ob: *buf, text: *buf, lang: *buf, opaque: *libc::c_void) {
unsafe {
@ -155,6 +163,45 @@ pub fn render(w: &mut io::Writer, s: &str) -> fmt::Result {
}
}
extern fn header(ob: *buf, text: *buf, level: libc::c_int,
_opaque: *libc::c_void) {
// sundown does this, we may as well too
"\n".with_c_str(|p| unsafe { bufputs(ob, p) });
// Extract the text provided
let s = if text.is_null() {
~""
} else {
unsafe {
str::raw::from_buf_len((*text).data, (*text).size as uint)
}
};
// Transform the contents of the header into a hyphenated string
let id = s.words().map(|s| {
match s.to_ascii_opt() {
Some(s) => s.to_lower().into_str(),
None => s.to_owned()
}
}).to_owned_vec().connect("-");
// Make sure our hyphenated ID is unique for this page
let id = local_data::get_mut(used_header_map, |map| {
let map = map.unwrap();
match map.find_mut(&id) {
None => {}
Some(a) => { *a += 1; return format!("{}-{}", id, *a - 1) }
}
map.insert(id.clone(), 1);
id.clone()
});
// Render the HTML
let text = format!(r#"<h{lvl} id="{id}">{}</h{lvl}>"#,
Escape(s.as_slice()), lvl = level, id = id);
text.with_c_str(|p| unsafe { bufputs(ob, p) });
}
// This code is all lifted from examples/sundown.c in the sundown repo
unsafe {
let ob = bufnew(OUTPUT_UNIT);
@ -175,9 +222,10 @@ pub fn render(w: &mut io::Writer, s: &str) -> fmt::Result {
sdhtml_renderer(&callbacks, &options, 0);
let opaque = my_opaque {
opt: options,
dfltblk: callbacks.blockcode,
dfltblk: callbacks.blockcode.unwrap(),
};
callbacks.blockcode = block;
callbacks.blockcode = Some(block);
callbacks.header = Some(header);
let markdown = sd_markdown_new(extensions, 16, &callbacks,
&opaque as *my_opaque as *libc::c_void);
@ -225,7 +273,10 @@ pub fn find_testable_code(doc: &str, tests: &mut ::test::Collector) {
MKDEXT_FENCED_CODE | MKDEXT_AUTOLINK |
MKDEXT_STRIKETHROUGH;
let callbacks = sd_callbacks {
blockcode: block,
blockcode: Some(block),
blockquote: None,
blockhtml: None,
header: None,
other: mem::init()
};
@ -239,6 +290,18 @@ pub fn find_testable_code(doc: &str, tests: &mut ::test::Collector) {
}
}
/// By default this markdown renderer generates anchors for each header in the
/// rendered document. The anchor name is the contents of the header spearated
/// by hyphens, and a task-local map is used to disambiguate among duplicate
/// headers (numbers are appended).
///
/// This method will reset the local table for these headers. This is typically
/// used at the beginning of rendering an entire HTML page to reset from the
/// previous state (if any).
pub fn reset_headers() {
local_data::set(used_header_map, HashMap::new())
}
impl<'a> fmt::Show for Markdown<'a> {
fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
let Markdown(md) = *self;

40
src/librustdoc/html/render.rs
View file

@ -52,6 +52,7 @@ use doctree;
use fold::DocFolder;
use html::format::{VisSpace, Method, PuritySpace};
use html::layout;
use html::markdown;
use html::markdown::Markdown;
use html::highlight;
@ -749,6 +750,8 @@ impl Context {
title: title,
};
markdown::reset_headers();
// We have a huge number of calls to write, so try to alleviate some
// of the pain by using a buffered writer instead of invoking the
// write sycall all the time.
@ -1001,24 +1004,25 @@ fn item_module(w: &mut Writer, cx: &Context,
try!(write!(w, "</table>"));
}
curty = myty;
try!(write!(w, "<h2>{}</h2>\n<table>", match myitem.inner {
clean::ModuleItem(..) => "Modules",
clean::StructItem(..) => "Structs",
clean::EnumItem(..) => "Enums",
clean::FunctionItem(..) => "Functions",
clean::TypedefItem(..) => "Type Definitions",
clean::StaticItem(..) => "Statics",
clean::TraitItem(..) => "Traits",
clean::ImplItem(..) => "Implementations",
clean::ViewItemItem(..) => "Reexports",
clean::TyMethodItem(..) => "Type Methods",
clean::MethodItem(..) => "Methods",
clean::StructFieldItem(..) => "Struct Fields",
clean::VariantItem(..) => "Variants",
clean::ForeignFunctionItem(..) => "Foreign Functions",
clean::ForeignStaticItem(..) => "Foreign Statics",
clean::MacroItem(..) => "Macros",
}));
let (short, name) = match myitem.inner {
clean::ModuleItem(..) => ("modules", "Modules"),
clean::StructItem(..) => ("structs", "Structs"),
clean::EnumItem(..) => ("enums", "Enums"),
clean::FunctionItem(..) => ("functions", "Functions"),
clean::TypedefItem(..) => ("types", "Type Definitions"),
clean::StaticItem(..) => ("statics", "Statics"),
clean::TraitItem(..) => ("traits", "Traits"),
clean::ImplItem(..) => ("impls", "Implementations"),
clean::ViewItemItem(..) => ("reexports", "Reexports"),
clean::TyMethodItem(..) => ("tymethods", "Type Methods"),
clean::MethodItem(..) => ("methods", "Methods"),
clean::StructFieldItem(..) => ("fields", "Struct Fields"),
clean::VariantItem(..) => ("variants", "Variants"),
clean::ForeignFunctionItem(..) => ("ffi-fns", "Foreign Functions"),
clean::ForeignStaticItem(..) => ("ffi-statics", "Foreign Statics"),
clean::MacroItem(..) => ("macros", "Macros"),
};
try!(write!(w, "<h2 id='{}'>{}</h2>\n<table>", short, name));
}
match myitem.inner {

7
src/librustdoc/html/static/main.css
View file

@ -319,3 +319,10 @@ pre.rust .macro, pre.rust .macro-nonterminal { color: #3E999f; }
pre.rust .string { color: #718C00; }
pre.rust .lifetime { color: #C13928; }
pre.rust .attribute, pre.rust .attribute .ident { color: #C82829; }
h1 a.anchor,
h2 a.anchor,
h3 a.anchor { display: none; }
h1:hover a.anchor,
h2:hover a.anchor,
h3:hover a.anchor { display: inline-block; }

7
src/librustdoc/html/static/main.js
View file

@ -599,4 +599,11 @@
}
initSearch(searchIndex);
$.each($('h1, h2, h3'), function(idx, element) {
if ($(element).attr('id') != undefined) {
$(element).append('<a href="#' + $(element).attr('id') + '" ' +
'class="anchor"> § </a>');
}
});
}());