Skip to content
This repository was archived by the owner on Apr 12, 2024. It is now read-only.

Fix docs - guide $location example #651

Closed
wants to merge 4 commits into from
+60 −48
Closed

Fix docs - guide $location example #651

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
564fad8
feat(docs): allow custom attributes on <doc:source>
vojtajina Nov 12, 2011
3137e56
feat(docs): allow examples with hidden source code
vojtajina Nov 12, 2011
25e291c
fix(docs.guide): fix $location example
vojtajina Nov 12, 2011
bd5c691
style(docs): make jslint happy - fix some warnings
vojtajina Nov 12, 2011
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 14 additions & 10 deletions docs/content/guide/dev_guide.services.$location.ngdoc
View file
Original file line number Diff line number Diff line change
@@ -369,8 +369,10 @@ redirect to regular / hashbang url, as this conversion happens only during parsi

In this examples we use `<base href="/base/index.html" />`

<ul class="doc-example">
<li ng:non-bindable class="html5-hashbang-example">
<doc:example>
<doc:source source="false">

<div ng:non-bindable class="html5-hashbang-example">
<div id="html5-mode" ng:controller="Html5Cntl">
<h3>Browser with History API</h3>
<ng:address-bar browser="html5"></ng:address-bar><br /><br />
@@ -380,9 +382,9 @@ In this examples we use `<base href="/base/index.html" />`
$location.path() = {{$location.path()}}<br />
$location.search() = {{$location.search()}}<br />
$location.hash() = {{$location.hash()}}<br />
<a href="/base/first?a=b">/base/first?a=b</a> | <a
href="sec/ond?flag#hash">sec/ond?flag#hash</a> | <a href="/base/another?search"
ng:ext-link>external</a>
<a href="/base/first?a=b">/base/first?a=b</a> |
<a href="sec/ond?flag#hash">sec/ond?flag#hash</a> |
<a href="/base/another?search" ng:ext-link>external</a>
</div>

<div id="hashbang-mode" ng:controller="HashbangCntl">
@@ -394,12 +396,11 @@ ng:ext-link>external</a>
$location.path() = {{$location.path()}}<br />
$location.search() = {{$location.search()}}<br />
$location.hash() = {{$location.hash()}}<br />
<a href="/base/first?a=b">/base/first?a=b</a> | <a
href="sec/ond?flag#hash">sec/ond?flag#hash</a> | <a href="/base/another?search"
ng:ext-link>external</a>
<a href="/base/first?a=b">/base/first?a=b</a> |
<a href="sec/ond?flag#hash">sec/ond?flag#hash</a> |
<a href="/base/another?search" ng:ext-link>external</a>
</div>
</li>
</ul>
</div>

<script type="text/javascript">
function FakeBrowser(initUrl, baseHref) {
@@ -481,6 +482,9 @@ ng:ext-link>external</a>
initEnv('hashbang');
</script>

</doc:source>
</doc:example>


# Caveats

8 changes: 8 additions & 0 deletions docs/spec/ngdocSpec.js
View file
Original file line number Diff line number Diff line change
@@ -89,6 +89,14 @@ describe('ngdoc', function() {
'<pre class="doc-source">\n&lt;&gt;\n</pre></doc:example><p>after</p>');
});

it('should preserve the source attribute', function() {
var doc = new Doc('@description before <doc:example>' +
'<doc:source source="false">lala</doc:source></doc:example> after');
doc.parse();
expect(doc.description).toContain('<p>before </p><doc:example>' +
'<pre class="doc-source" source="false">lala</pre></doc:example><p>after</p>');
});

it('should preserve the jsfiddle attribute', function() {
var doc = new Doc('@description before <doc:example>' +
'<doc:source jsfiddle="foo">lala</doc:source></doc:example> after');
36 changes: 18 additions & 18 deletions docs/src/ngdoc.js
View file
Original file line number Diff line number Diff line change
@@ -117,9 +117,9 @@ Doc.prototype = {
'</pre></div>';
});
} else if (isDocWidget('example')) {
text = text.replace(/<doc:source(\s+jsfiddle="[^"]+")?>([\s\S]*)<\/doc:source>/mi,
function(_, jsfiddle, content){
return '<pre class="doc-source"' + (jsfiddle || '') +'>' +
text = text.replace(/<doc:source(\s+[^>]*)?>([\s\S]*)<\/doc:source>/mi,
function(_, attrs, content){
return '<pre class="doc-source"' + (attrs || '') +'>' +
htmlEscape(content) +
'</pre>';
});
@@ -138,11 +138,11 @@ Doc.prototype = {

if (!isFullUrl) self.links.push(absUrl);

return '<a href="' + absUrl + '">'
+ (isAngular ? '<code>' : '')
+ (title || url).replace(/\n/g, ' ')
+ (isAngular ? '</code>' : '')
+ '</a>';
return '<a href="' + absUrl + '">' +
(isAngular ? '<code>' : '') +
(title || url).replace(/\n/g, ' ') +
(isAngular ? '</code>' : '') +
'</a>';
});
text = new Showdown.converter().makeHtml(text);
}
@@ -157,7 +157,7 @@ Doc.prototype = {
var match;
var self = this;
self.text.split(NEW_LINE).forEach(function(line){
if (match = line.match(/^\s*@(\w+)(\s+(.*))?/)) {
if ((match = line.match(/^\s*@(\w+)(\s+(.*))?/))) {
// we found @name ...
// if we have existing name
flush();
@@ -172,19 +172,19 @@ Doc.prototype = {
});
flush();
this.shortName = (this.name || '').split(/[\.#]/).pop();
this.id = this.id // if we have an id just use it
|| (((this.file||'').match(/.*\/([^\/]*)\.ngdoc/)||{})[1]) // try to extract it from file name
|| this.name; // default to name
this.id = this.id || // if we have an id just use it
(((this.file||'').match(/.*\/([^\/]*)\.ngdoc/)||{})[1]) || // try to extract it from file name
this.name; // default to name
this.description = this.markdown(this.description);
this.example = this.markdown(this.example);
this['this'] = this.markdown(this['this']);
return this;

function flush() {
if (atName) {
var text = trim(atText.join('\n'));
var text = trim(atText.join('\n')), match;
if (atName == 'param') {
var match = text.match(/^{([^}=]+)(=)?}\s+(([^\s=]+)|\[(\S+)=([^\]]+)\])\s+(.*)/);
match = text.match(/^\{([^}=]+)(=)?\}\s+(([^\s=]+)|\[(\S+)=([^\]]+)\])\s+(.*)/);
// 1 12 2 34 4 5 5 6 6 3 7 7
if (!match) {
throw new Error("Not a valid 'param' format: " + text);
@@ -198,7 +198,7 @@ Doc.prototype = {
};
self.param.push(param);
} else if (atName == 'returns') {
var match = text.match(/^{([^}=]+)}\s+(.*)/);
match = text.match(/^\{([^}=]+)\}\s+(.*)/);
if (!match) {
throw new Error("Not a valid 'returns' format: " + text);
}
@@ -207,13 +207,13 @@ Doc.prototype = {
description: self.markdown(text.replace(match[0], match[2]))
};
} else if(atName == 'requires') {
var match = text.match(/^([^\s]*)\s*([\S\s]*)/);
match = text.match(/^([^\s]*)\s*([\S\s]*)/);
self.requires.push({
name: match[1],
text: self.markdown(match[2])
});
} else if(atName == 'property') {
var match = text.match(/^{(\S+)}\s+(\S+)(\s+(.*))?/);
match = text.match(/^\{(\S+)\}\s+(\S+)(\s+(.*))?/);
if (!match) {
throw new Error("Not a valid 'property' format: " + text);
}
@@ -224,7 +224,7 @@ Doc.prototype = {
};
self.properties.push(property);
} else if(atName == 'eventType') {
var match = text.match(/^([^\s]*)\s+on\s+([\S\s]*)/);
match = text.match(/^([^\s]*)\s+on\s+([\S\s]*)/);
self.type = match[1];
self.target = match[2];
} else {
29 changes: 20 additions & 9 deletions docs/src/templates/doc_widgets.js
View file
Original file line number Diff line number Diff line change
@@ -28,19 +28,28 @@
//jqlite instead. jqlite's find() method currently supports onlt getElementsByTagName!
var example = element.find('pre').eq(0), //doc-source
exampleSrc = example.text(),
showSource = example.attr('source') !== 'false',
jsfiddle = example.attr('jsfiddle') || true,
scenario = element.find('pre').eq(1); //doc-scenario

var code = indent(exampleSrc);
var tabHtml =
'<ul class="doc-example">' +
'<ul class="doc-example">';

// show source tab, if not disabled
if (showSource) {
tabHtml +=
'<li class="doc-example-heading"><h3>Source</h3></li>' +
'<li class="doc-example-source" ng:non-bindable>' +
jsFiddleButton(jsfiddle) + // may or may not have value
'<pre class="brush: js; html-script: true; highlight: [' +
code.hilite + ']; toolbar: false;"></pre></li>' +
code.hilite + ']; toolbar: false;"></pre></li>';
}
// show live preview tab
tabHtml +=
'<li class="doc-example-heading"><h3>Live Preview</h3></li>' +
'<li class="doc-example-live">' + exampleSrc +'</li>';
// show scenario tab, if present
if (scenario.text()) {
tabHtml +=
'<li class="doc-example-heading"><h3>Scenario Test</h3></li>' +
@@ -69,14 +78,14 @@

function jsFiddleButton(jsfiddle) {
if (jsfiddle !== 'false') {
if(jsfiddle == true) {
if(jsfiddle === true) {
//dynamically generate a fiddle
var fiddleUrl = 'http://jsfiddle.net/api/post/library/pure/',
fiddleSrc = exampleSrc,
stripIndent = fiddleSrc.match(/^(\s*)/)[1].length;

//escape closing textarea
fiddleSrc = fiddleSrc.replace(/<\/textarea>/gi,'&lt;/textarea&gt;')
fiddleSrc = fiddleSrc.replace(/<\/textarea>/gi,'&lt;/textarea&gt;');
//strip extra indentation
fiddleSrc = fiddleSrc.replace(new RegExp('^\\s{' + stripIndent + '}', 'gm'), '');

@@ -113,25 +122,27 @@
if (!text) return text;
var lines = text.split(/\r?\n/);
var lineNo = [];
var i;

// remove any leading blank lines
while (lines[0].match(/^\s*$/)) lines.shift();
// remove any trailing blank lines
while (lines[lines.length - 1].match(/^\s*$/)) lines.pop();
var minIndent = 999;
for ( var i = 0; i < lines.length; i++) {
for (i = 0; i < lines.length; i++) {
var line = lines[0];
var indent = line.match(/^\s*/)[0];
if (indent !== line && indent.length < minIndent) {
minIndent = indent.length;
}
}

for ( var i = 0; i < lines.length; i++) {
for (i = 0; i < lines.length; i++) {
lines[i] = ' ' + lines[i].substring(minIndent);
lineNo.push(5 + i);
}
return {html: lines.join('\n'), hilite: lineNo.join(',') };
};
}

var HTML_TPL =
'<p><a ng:init="showInstructions = {show}" ng:show="!showInstructions" ng:click="showInstructions = true" href>Workspace Reset Instructions &nbsp;&#x27A4;</a></p>' +
@@ -199,8 +210,8 @@
if (children.length) {
// load custom content
angular.forEach(element.children(), function(elm) {
var elm = angular.element(elm),
id = elm.attr('id');
elm = angular.element(elm);
var id = elm.attr('id');

nav.append(HTML_NAV.replace('{title}', elm.attr('title')).replace(/\{id\}/g, id));
content.append(HTML_CONTENT.replace('{id}', id).replace('{content}', elm.html()));
11 changes: 0 additions & 11 deletions docs/src/templates/docs.css
View file
Original file line number Diff line number Diff line change
@@ -467,17 +467,6 @@ td.empty-corner-lt {
}

/* service.$location Html5 mode example */
.html5-hashbang-example {
height: 255px;
margin-left: -40px;
padding-left: 30px;
}

.html5-hashbang-example div {
float: left;
width: 375px;
}

.html5-hashbang-example div input {
width: 360px;
}