New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Reusable Sass utilities API documentation section #39756
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,82 @@ | ||
{{- /* | ||
Usage: `scss-docs name="name" file="file/_location.scss"` | ||
|
||
Prints everything between `// scss-docs-start "name"` and `// scss-docs-end "name"` | ||
comments in the docs. | ||
|
||
Optional parameters: | ||
* strip-default: Remove the ` !default` flag from variable assignments - default: `true` | ||
*/ -}} | ||
|
||
{{- $name := .Params.name -}} | ||
{{- $file := .Params.file -}} | ||
{{- $strip_default := .Get "strip-default" | default "true" -}} | ||
|
||
{{- /* If any parameters are missing, print an error and exit */ -}} | ||
{{- if or (not $name) (not $file) -}} | ||
{{- errorf "%s: %q: Missing required parameters! Got: name=%q file=%q!" .Position .Name $name $file -}} | ||
{{- else -}} | ||
{{- $capture_start := printf "// scss-docs-start %s\n" $name -}} | ||
{{- $capture_end := printf "// scss-docs-end %s\n" $name -}} | ||
{{- $regex := printf `%s((?:.|\n)*)%s` $capture_start $capture_end -}} | ||
{{- $regex_nested := printf `// scss-docs-.*\n` -}} | ||
|
||
{{- /* | ||
TODO: figure out why we can't do the following and get the first group (the only capturing one)... | ||
$regex := printf `(?:// scss-docs-start %s\n)((?:.|\n)*)(?:\n// scss-docs-end %s)` $name $name | ||
*/ -}} | ||
|
||
{{- $match := findRE $regex (readFile $file) -}} | ||
{{- $match = index $match 0 -}} | ||
|
||
{{- if not $match -}} | ||
{{- errorf "%s: %q: Got no matches for name=%q in file=%q!" .Position .Name $name $file -}} | ||
{{- end -}} | ||
|
||
{{- $match = replace $match $capture_start "" -}} | ||
{{- $match = replace $match $capture_end "" -}} | ||
|
||
{{- $match_nested := findRE $regex_nested $match -}} | ||
{{- range $to_remove := $match_nested -}} | ||
{{- $match = replace $match $to_remove "" -}} | ||
{{- end -}} | ||
|
||
{{- if (ne $strip_default "false") -}} | ||
{{- $match = replace $match " !default" "" -}} | ||
{{- end -}} | ||
|
||
<div class="bd-example-snippet bd-code-snippet bd-file-ref"> | ||
<div class="d-flex align-items-center highlight-toolbar ps-3 pe-2 py-1 border-bottom"> | ||
<a class="font-monospace link-secondary link-underline-secondary link-underline-opacity-0 link-underline-opacity-100-hover small" href="{{ .Site.Params.repo }}/blob/v{{ .Site.Params.current_version }}/{{ $file | replaceRE `\\` "/" }}"> | ||
{{- $file -}} | ||
</a> | ||
<div class="d-flex ms-auto"> | ||
<button type="button" class="btn-clipboard mt-0 me-0" title="Copy to clipboard"> | ||
<svg class="bi" aria-hidden="true"><use xlink:href="#clipboard"/></svg> | ||
</button> | ||
</div> | ||
</div> | ||
{{- $unindent := 0 -}} | ||
{{- $found := false -}} | ||
{{- $first_line:= index (split $match "\n") 0 -}} | ||
{{- range $char := split $first_line "" -}} | ||
{{- if and (eq $char " ") (not $found) -}} | ||
{{- $unindent = add $unindent 1 -}} | ||
{{- else -}} | ||
{{- $found = true -}} | ||
{{- end -}} | ||
{{- end -}} | ||
{{- $output := "" -}} | ||
{{- if (gt $unindent 0) -}} | ||
{{- $prefix := (strings.Repeat $unindent " ") -}} | ||
{{- range $line := split $match "\n" -}} | ||
{{- $line = strings.TrimPrefix $prefix $line -}} | ||
{{ $output = printf "%s%s\n" $output $line }} | ||
{{- end -}} | ||
{{- $output = chomp $output -}} | ||
{{- else -}} | ||
{{- $output = $match -}} | ||
{{- end -}} | ||
{{- highlight $output "scss" "" -}} | ||
</div> | ||
{{- end -}} |
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. FYI, some refactoring is happening in our docs right now. I haven't voluntarily clicked on "Update branch" to avoid breaking your changes. I'll let you rebase your branch yourself and adapt your changes to the latest modifications. This There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Certainly! When the refactoring is over, I can rebase my branch. Are you tracking these refactorings in any issue? If you think it's safe, I can do it as soon as I can and look at the borders.md issue as well There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think you can rebase it from now on. There's no tracking issue; it's basically all the commits from this week and last week. They won't probably have any impacts on your PR directly, but some elements would maybe need to be backported here; I'll take care of it when the PR is rebased as it might be difficult and long for you to handle :) |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,2 +1,9 @@ | ||
{{- $pageToReference := path.Join "docs" $.Site.Params.docs_version (.Get 0) -}} | ||
{{- $urlPath := .Get "urlPath" -}} | ||
|
||
{{- if and (not $urlPath) (index .Params 0) -}} | ||
{{- $urlPath = index .Params 0 -}} | ||
{{- end -}} | ||
|
||
{{- $pageToReference := path.Join "docs" $.Site.Params.docs_version $urlPath -}} | ||
|
||
{{- relref . $pageToReference | relURL -}} |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
<h3>Sass utilities API</h3> | ||
|
||
<p> | ||
{{ index .Params.title }} utilities are declared in our utilities API in <code>scss/_utilities.scss</code>. <a href="{{ replaceRE "(\\s)" "" .Inner }}">Learn how to use the utilities API.</a> | ||
</p> | ||
|
||
{{- partial "scss-docs" . -}} |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,82 +1 @@ | ||
{{- /* | ||
Usage: `scss-docs name="name" file="file/_location.scss"` | ||
|
||
Prints everything between `// scss-docs-start "name"` and `// scss-docs-end "name"` | ||
comments in the docs. | ||
|
||
Optional parameters: | ||
* strip-default: Remove the ` !default` flag from variable assignments - default: `true` | ||
*/ -}} | ||
|
||
{{- $name := .Get "name" -}} | ||
{{- $file := .Get "file" -}} | ||
{{- $strip_default := .Get "strip-default" | default "true" -}} | ||
|
||
{{- /* If any parameters are missing, print an error and exit */ -}} | ||
{{- if or (not $name) (not $file) -}} | ||
{{- errorf "%s: %q: Missing required parameters! Got: name=%q file=%q!" .Position .Name $name $file -}} | ||
{{- else -}} | ||
{{- $capture_start := printf "// scss-docs-start %s\n" $name -}} | ||
{{- $capture_end := printf "// scss-docs-end %s\n" $name -}} | ||
{{- $regex := printf `%s((?:.|\n)*)%s` $capture_start $capture_end -}} | ||
{{- $regex_nested := printf `// scss-docs-.*\n` -}} | ||
|
||
{{- /* | ||
TODO: figure out why we can't do the following and get the first group (the only capturing one)... | ||
$regex := printf `(?:// scss-docs-start %s\n)((?:.|\n)*)(?:\n// scss-docs-end %s)` $name $name | ||
*/ -}} | ||
|
||
{{- $match := findRE $regex (readFile $file) -}} | ||
{{- $match = index $match 0 -}} | ||
|
||
{{- if not $match -}} | ||
{{- errorf "%s: %q: Got no matches for name=%q in file=%q!" .Position .Name $name $file -}} | ||
{{- end -}} | ||
|
||
{{- $match = replace $match $capture_start "" -}} | ||
{{- $match = replace $match $capture_end "" -}} | ||
|
||
{{- $match_nested := findRE $regex_nested $match -}} | ||
{{- range $to_remove := $match_nested -}} | ||
{{- $match = replace $match $to_remove "" -}} | ||
{{- end -}} | ||
|
||
{{- if (ne $strip_default "false") -}} | ||
{{- $match = replace $match " !default" "" -}} | ||
{{- end -}} | ||
|
||
<div class="bd-example-snippet bd-code-snippet bd-file-ref"> | ||
<div class="d-flex align-items-center highlight-toolbar ps-3 pe-2 py-1 border-bottom"> | ||
<a class="font-monospace link-secondary link-underline-secondary link-underline-opacity-0 link-underline-opacity-100-hover small" href="{{ .Site.Params.repo }}/blob/v{{ .Site.Params.current_version }}/{{ $file | replaceRE `\\` "/" }}"> | ||
{{- $file -}} | ||
</a> | ||
<div class="d-flex ms-auto"> | ||
<button type="button" class="btn-clipboard mt-0 me-0" title="Copy to clipboard"> | ||
<svg class="bi" aria-hidden="true"><use xlink:href="#clipboard"/></svg> | ||
</button> | ||
</div> | ||
</div> | ||
{{- $unindent := 0 -}} | ||
{{- $found := false -}} | ||
{{- $first_line:= index (split $match "\n") 0 -}} | ||
{{- range $char := split $first_line "" -}} | ||
{{- if and (eq $char " ") (not $found) -}} | ||
{{- $unindent = add $unindent 1 -}} | ||
{{- else -}} | ||
{{- $found = true -}} | ||
{{- end -}} | ||
{{- end -}} | ||
{{- $output := "" -}} | ||
{{- if (gt $unindent 0) -}} | ||
{{- $prefix := (strings.Repeat $unindent " ") -}} | ||
{{- range $line := split $match "\n" -}} | ||
{{- $line = strings.TrimPrefix $prefix $line -}} | ||
{{ $output = printf "%s%s\n" $output $line }} | ||
{{- end -}} | ||
{{- $output = chomp $output -}} | ||
{{- else -}} | ||
{{- $output = $match -}} | ||
{{- end -}} | ||
{{- highlight $output "scss" "" -}} | ||
</div> | ||
{{- end -}} | ||
{{- partial "scss-docs" . }} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There's an edge case I haven't seen before in
borders.md
where there are two calls toscss-docs
:Let's perhaps wait for the discussion on the global approach to take place and not tackle it right away if it's too complicated, but here we might need to manage an array of names instead of a simple
name="utils-overflow"
.This comment was marked as off-topic.
Sorry, something went wrong.