Skip to content

Commit efc113e

Browse files
nex3nex3
committed
[WIP] Reference
1 parent 56f97b7 commit efc113e

File tree

62 files changed

+6210
-77
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

62 files changed

+6210
-77
lines changed

‎helpers/sass_helpers.rb‎

Lines changed: 70 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ def pages_for_group(group_name)
8888
#
8989
# A third section may optionally be provided to represent compiled CSS. If
9090
# it's not passed and `autogen_css` is `true`, it's generated from the SCSS
91-
# source.
91+
# source. If the autogenerated CSS is empty, it's omitted entirely.
9292
#
9393
# If `syntax` is either `:sass` or `:scss`, the first section will be
9494
# interpreted as that syntax and the second will be interpreted (or
@@ -109,12 +109,18 @@ def example(autogen_css: true, syntax: nil, &block)
109109
sass_sections = sass ? sass.split("\n---\n").map(&:strip) : []
110110

111111
if css.nil? && autogen_css
112-
if scss_sections.length != 1
112+
sections = scss ? scss_sections : sass_sections
113+
if sections.length != 1
113114
throw ArgumentError.new(
114115
"Can't auto-generate CSS from more than one SCSS file.")
115116
end
116117

117-
css = Sass::Engine.new(scss, syntax: :scss, style: :expanded).render
118+
css = Sass::Engine.new(
119+
sections.first,
120+
syntax: syntax || :scss,
121+
style: :expanded
122+
).render
123+
css = nil if css.empty?
118124
end
119125
css_sections = css ? css.split("\n---\n").map(&:strip) : []
120126

@@ -195,13 +201,16 @@ def example(autogen_css: true, syntax: nil, &block)
195201
if block_is_haml?(block)
196202
haml_concat text
197203
else
198-
concat text
204+
# Padrino's concat helper doesn't play nice with nested captures.
205+
@_out_buf << text
199206
end
200207
end
201208

202209
# Returns the number of lines of padding that's needed to match the height of
203210
# the `<pre>`s generated for `sections1` and `sections2`.
204211
def _total_padding(sections1, sections2)
212+
sections1 ||= []
213+
sections2 ||= []
205214
[sections1, sections1].map(&:length).max.times.sum do |i|
206215
# Add 2 lines to each additional section: 1 for the extra padding, and 1
207216
# for the extra margin.
@@ -253,15 +262,27 @@ def release_url(impl)
253262
end
254263
end
255264

256-
# Returns HTML for a note about the given implementation.
265+
# Returns HTML for a warning.
257266
#
258267
# The contents should be supplied as a block.
259-
def impl_note
268+
def heads_up
260269
concat(content_tag :aside, [
261270
content_tag(:i, 'TODO(jina): style this div'),
262-
content_tag(:strong, 'Implementation note:'),
271+
content_tag(:strong, 'Heads up!'),
263272
_render_markdown(capture {yield})
264-
], class: 'impl-note')
273+
], class: 'warning')
274+
end
275+
276+
# Returns HTML for a fun fact that's not directly relevant to the main
277+
# documentation.
278+
#
279+
# The contents should be supplied as a block.
280+
def fun_fact
281+
concat(content_tag :aside, [
282+
content_tag(:i, 'TODO(jina): style this div'),
283+
content_tag(:strong, 'Fun fact:'),
284+
_render_markdown(capture {yield})
285+
], class: 'fun-fact')
265286
end
266287

267288
# Renders a status dashboard for each implementation's support for a feature.
@@ -272,16 +293,27 @@ def impl_note
272293
# supporting the feature.
273294
#
274295
# When possible, prefer using the start version rather than `true`.
296+
#
297+
# This takes a Markdown block that should provide more information about the
298+
# implementation differences or the old behavior.
275299
def impl_status(dart: nil, libsass: nil, ruby: nil)
276300
raise ArgumentError.new("Missing argument dart.") if dart.nil?
277301
raise ArgumentError.new("Missing argument libsass.") if libsass.nil?
278302
raise ArgumentError.new("Missing argument ruby.") if ruby.nil?
279303

280-
content_tag :table, [
304+
contents = [
281305
_impl_status_row('Dart Sass', dart),
282306
_impl_status_row('LibSass', libsass),
283307
_impl_status_row('Ruby Sass', ruby),
284-
], class: 'impl-status'
308+
]
309+
310+
if block_given?
311+
contents.unshift(content_tag(:caption, [
312+
_render_markdown(capture {yield})
313+
]))
314+
end
315+
316+
concat(content_tag :table, contents, class: 'impl-status')
285317
end
286318

287319
# Renders a single row for `impl_status`.
@@ -301,6 +333,34 @@ def _impl_status_row(name, status)
301333
], class: status ? 'supported' : 'unsupported'
302334
end
303335

336+
# Renders API docs for a Sass function.
337+
#
338+
# The function's name is parsed from the signature. The API description is
339+
# passed as a Markdown block. If `returns` is passed, it's included as the function's return type.
340+
def function(signature, returns: nil)
341+
name = signature.split("(").first
342+
html = Nokogiri::HTML(_render_markdown(<<MARKDOWN))
343+
```scss
344+
@function #{signature}
345+
{}
346+
```
347+
MARKDOWN
348+
highlighted_signature = html.css("pre code").children.
349+
drop_while {|el| el.text != "@function"}.
350+
take_while {|el| el.text != "{}"}[1...-1].
351+
map(&:to_html).join.strip
352+
353+
concat(content_tag :div, [
354+
content_tag(:pre, [
355+
content_tag(:code, highlighted_signature)
356+
], class: 'signature highlight scss'),
357+
358+
returns ? content_tag(:div, returns, class: 'return-type') : '',
359+
360+
_render_markdown(capture {yield})
361+
], class: 'function', id: name)
362+
end
363+
304364
# A helper method that renders a chunk of Markdown text.
305365
def _render_markdown(content)
306366
@redcarpet ||= Redcarpet::Markdown.new(

‎source/assets/css/components/_railroad.scss‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
/*! Railroad diagram styles copyright © 2018 W3C® (MIT, ERCIM, Keio, Beihang).
2+
* W3C liability, trademark and permissive document license rules apply.
3+
* http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer
4+
* http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks
5+
* http://www.w3.org/Consortium/Legal/2015/copyright-software-and-document */
6+
7+
svg.railroad-diagram {
8+
background-color: hsl(30,20%,95%);
9+
10+
path {
11+
stroke-width: 3px;
12+
stroke: black;
13+
fill: rgba(0,0,0,0);
14+
}
15+
16+
text {
17+
font:bold 14px monospace;
18+
text-anchor:middle;
19+
}
20+
21+
text.label {
22+
text-anchor:start;
23+
}
24+
25+
text.comment {
26+
font: italic 12px monospace;
27+
}
28+
29+
rect {
30+
stroke-width: 3px;
31+
stroke: black;
32+
fill: hsl(120,100%,90%);
33+
}
34+
}

‎source/assets/css/sass.css.scss‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@
7171
, "components/icons"
7272
, "components/logos"
7373
, "components/sass-syntax-switcher"
74+
, "components/railroad"
7475
;
7576

7677

‎source/assets/img/illustrations/_identifier-diagram.html.erb‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
<figure>
2+
<%# From https://drafts.csswg.org/css-syntax-3/#ident-token-diagram %>
3+
<svg class="railroad-diagram" height="130" viewBox="0 0 768 130" width="768">
4+
<g transform="translate(.5 .5)">
5+
<path d="M 20 51 v 20 m 10 -20 v 20 m -10 -10 h 20.5"></path>
6+
<g>
7+
<path d="M40 61h0"></path>
8+
<path d="M384 61h0"></path>
9+
<path d="M40 61a10 10 0 0 0 10 -10v-10a10 10 0 0 1 10 -10"></path>
10+
<g class="terminal">
11+
<path d="M60 31h134"></path>
12+
<path d="M230 31h134"></path>
13+
<rect height="22" rx="10" ry="10" width="36" x="194" y="20"></rect>
14+
<text x="212" y="35">&#45;&#45;</text>
15+
</g>
16+
<path d="M364 31a10 10 0 0 1 10 10v10a10 10 0 0 0 10 10"></path>
17+
<path d="M40 61h20"></path>
18+
<g>
19+
<path d="M60 61h0"></path>
20+
<path d="M364 61h0"></path>
21+
<g>
22+
<path d="M60 61h0"></path>
23+
<path d="M128 61h0"></path>
24+
<path d="M60 61h20"></path>
25+
<g>
26+
<path d="M80 61h28"></path>
27+
</g>
28+
<path d="M108 61h20"></path>
29+
<path d="M60 61a10 10 0 0 1 10 10v0a10 10 0 0 0 10 10"></path>
30+
<g class="terminal">
31+
<path d="M80 81h0"></path>
32+
<path d="M108 81h0"></path>
33+
<rect height="22" rx="10" ry="10" width="28" x="80" y="70"></rect>
34+
<text x="94" y="85">-</text>
35+
<text x="94" y="85">-</text>
36+
</g>
37+
<path d="M108 81a10 10 0 0 0 10 -10v0a10 10 0 0 1 10 -10"></path>
38+
</g>
39+
<g>
40+
<path d="M128 61h0"></path>
41+
<path d="M364 61h0"></path>
42+
<path d="M128 61h20"></path>
43+
<g class="non-terminal">
44+
<path d="M148 61h0"></path>
45+
<path d="M344 61h0"></path>
46+
<rect height="22" width="196" x="148" y="50"></rect>
47+
<text x="246" y="65">a-z A-Z _ or non-ASCII</text>
48+
<text x="246" y="65">a-z A-Z _ or non-ASCII</text>
49+
</g>
50+
<path d="M344 61h20"></path>
51+
<path d="M128 61a10 10 0 0 1 10 10v10a10 10 0 0 0 10 10"></path>
52+
<g class="non-terminal">
53+
<path d="M148 91h64"></path>
54+
<path d="M280 91h64"></path>
55+
<rect height="22" width="68" x="212" y="80"></rect>
56+
<text x="246" y="95">escape</text>
57+
<text x="246" y="95">escape</text>
58+
</g>
59+
<path d="M344 91a10 10 0 0 0 10 -10v-10a10 10 0 0 1 10 -10"></path>
60+
</g>
61+
</g>
62+
<path d="M364 61h20"></path>
63+
</g>
64+
<g>
65+
<path d="M384 61h0"></path>
66+
<path d="M728 61h0"></path>
67+
<path d="M384 61a10 10 0 0 0 10 -10v0a10 10 0 0 1 10 -10"></path>
68+
<g>
69+
<path d="M404 41h304"></path>
70+
</g>
71+
<path d="M708 41a10 10 0 0 1 10 10v0a10 10 0 0 0 10 10"></path>
72+
<path d="M384 61h20"></path>
73+
<g>
74+
<path d="M404 61h0"></path>
75+
<path d="M708 61h0"></path>
76+
<path d="M404 61h10"></path>
77+
<g>
78+
<path d="M414 61h0"></path>
79+
<path d="M698 61h0"></path>
80+
<path d="M414 61h20"></path>
81+
<g class="non-terminal">
82+
<path d="M434 61h0"></path>
83+
<path d="M678 61h0"></path>
84+
<rect height="22" width="244" x="434" y="50"></rect>
85+
<text x="556" y="65">a-z A-Z 0-9 _ - or non-ASCII</text>
86+
<text x="556" y="65">a-z A-Z 0-9 _ - or non-ASCII</text>
87+
</g>
88+
<path d="M678 61h20"></path>
89+
<path d="M414 61a10 10 0 0 1 10 10v10a10 10 0 0 0 10 10"></path>
90+
<g class="non-terminal">
91+
<path d="M434 91h88"></path>
92+
<path d="M590 91h88"></path>
93+
<rect height="22" width="68" x="522" y="80"></rect>
94+
<text x="556" y="95">escape</text>
95+
<text x="556" y="95">escape</text>
96+
</g>
97+
<path d="M678 91a10 10 0 0 0 10 -10v-10a10 10 0 0 1 10 -10"></path>
98+
</g>
99+
<path d="M698 61h10"></path>
100+
<path d="M414 61a10 10 0 0 0 -10 10v29a10 10 0 0 0 10 10"></path>
101+
<g>
102+
<path d="M414 110h284"></path>
103+
</g>
104+
<path d="M698 110a10 10 0 0 0 10 -10v-29a10 10 0 0 0 -10 -10"></path>
105+
</g>
106+
<path d="M708 61h20"></path>
107+
</g>
108+
<path d="M 728 61 h 20 m -10 -10 v 20 m 10 -20 v 20"></path>
109+
</g>
110+
</svg>
111+
<figcaption class="copyright">Railroad diagram copyright © 2018 W3C<sup>®</sup> (MIT, ERCIM, Keio, Beihang). W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/2015/copyright-software-and-document">permissive document license</a> rules apply.
112+
</figcaption>

0 commit comments

Comments
 (0)