Skip to content

Commit 944e7fc

Browse files
KixironJoshua Nelson
Kixiron
authored and
Joshua Nelson
committed
Added the ability to link to sections of about pages, fixed builds code indenting and added highlighting to metadata page
1 parent f71bf32 commit 944e7fc

File tree

5 files changed

+107
-71
lines changed

5 files changed

+107
-71
lines changed

‎src/web/page/templates.rs

Lines changed: 28 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -242,16 +242,40 @@ fn dbg(value: &Value, _args: &HashMap<String, Value>) -> TeraResult<Value> {
242242
}
243243

244244
/// Dedent a string by removing all leading whitespace
245-
fn dedent(value: &Value, _args: &HashMap<String, Value>) -> TeraResult<Value> {
245+
fn dedent(value: &Value, args: &HashMap<String, Value>) -> TeraResult<Value> {
246246
let string = value.as_str().expect("dedent takes a string");
247247

248-
Ok(Value::String(
248+
let unindented = if let Some(levels) = args
249+
.get("levels")
250+
.map(|l| l.as_i64().expect("`levels` must be an integer"))
251+
{
252+
string
253+
.lines()
254+
.map(|mut line| {
255+
for _ in 0..levels {
256+
// `.strip_prefix` returns `Some(suffix without prefix)` if it's successful. If it fails
257+
// to strip the prefix (meaning there's less than `levels` levels of indentation),
258+
// we can just quit early
259+
if let Some(suffix) = line.strip_prefix(" ") {
260+
line = suffix;
261+
} else {
262+
break;
263+
}
264+
}
265+
266+
line
267+
})
268+
.collect::<Vec<&str>>()
269+
.join("\n")
270+
} else {
249271
string
250272
.lines()
251273
.map(|l| l.trim_start())
252274
.collect::<Vec<&str>>()
253-
.join("\n"),
254-
))
275+
.join("\n")
276+
};
277+
278+
Ok(Value::String(unindented))
255279
}
256280

257281
enum IconType {

‎templates/core/about/builds.html

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -19,18 +19,18 @@ <h1>Builds</h1>
1919
{%- endif -%}
2020
</p>
2121

22-
<h3>Notes on using Docs.rs</h3>
22+
<h3 id="notes-on-docsrs">Notes on using Docs.rs</h3>
2323

24-
<h4>Setting a README</h4>
24+
<h4 id="setting-a-readme">Setting a README</h4>
2525
<p>
2626
The README of a crate is taken from the <code>readme</code> field defined in
2727
<code>Cargo.toml</code>. If this field is not set, no README will be displayed.
2828
</p>
2929

30-
<h4>Detecting Docs.rs</h4>
30+
<h4 id="detecting-docsrs">Detecting Docs.rs</h4>
3131
<p>
3232
To recognize Docs.rs from <code>build.rs</code> files, you can test for the environment variable <code>DOCS_RS</code>, e.g.:
33-
{% filter dedent -%}
33+
{% filter dedent(levels=4) -%}
3434
<pre>
3535
<code>
3636
if let Ok(_) = std::env::var("DOCS_RS") {
@@ -56,32 +56,32 @@ <h4>Detecting Docs.rs</h4>
5656
This approach is also useful for setting <a href="https://doc.rust-lang.org/cargo/reference/features.html">cargo features</a>.
5757
</p>
5858

59-
<h4>Testing documentation builds locally</h4>
59+
<h4 id="testing-builds-locally">Testing documentation builds locally</h4>
6060
{%- set build_subcommand = docsrs_repo ~ "/blob/master/README.md#build-subcommand" -%}
6161
<p>
6262
The Docs.rs <a href="{{ build_subcommand | safe }}">README</a> describes how to build
6363
unpublished crate documentation locally using the same build environment as the Docs.rs build agent.
6464
</p>
6565

66-
<h3>Diagnosing failed builds</h3>
66+
<h3 id="diagnosing-failed-builds">Diagnosing failed builds</h3>
6767

68-
<h4>Missing dependencies</h4>
68+
<h4 id="missing-dependencies">Missing dependencies</h4>
6969
<p>
7070
Missing dependencies are a common reason for failed builds.
7171
Docs.rs dependencies are managed through
7272
<a href="https://github.com/rust-lang/crates-build-env">crates-build-env</a>.
7373
See <a href="https://forge.rust-lang.org/docs-rs/add-dependencies.html">Forge</a> for how to add a dependency.
7474
</p>
7575

76-
<h4>Write attempt on read-only directories</h4>
76+
<h4 id="read-only-directories">Write attempt on read-only directories</h4>
7777
<p>
7878
Most of the sandbox is a read-only file system, including the source directory of your crate and its dependencies.
7979
If your <code>build.rs</code> generates files that are relevant for documentation, consider writing to the
8080
<a href="https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates">cargo output directory</a>,
8181
passed in the environment variable <code>OUT_DIR</code>.
8282
</p>
8383

84-
<h4>Hitting resource limits</h4>
84+
<h4 id="hitting-resource-limits">Hitting resource limits</h4>
8585
<p>
8686
All the builds are executed inside a sandbox with limited resources. The current limits are:
8787
</p>
@@ -96,7 +96,7 @@ <h4>Hitting resource limits</h4>
9696
However, network access will not be enabled for any crate.
9797
</p>
9898

99-
<h4>Other failures and requesting rebuilds</h4>
99+
<h4 id="failures-and-rebuilds">Other failures and requesting rebuilds</h4>
100100
<p>
101101
If your crate fails to build for a reason not listed here, please <a href="{{ docsrs_repo | safe }}/issues">file an issue</a>.
102102
Some build failures can be fixed by Docs.rs, e.g., by issuing a rebuild after a bug in Docs.rs has been fixed.

‎templates/core/about/index.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,18 +25,18 @@ <h1 id="crate-title">About Docs.rs</h1>
2525
</p>
2626

2727

28-
<h2>More about Docs.rs</h2>
28+
<h2 id="more-about-docsrs">More about Docs.rs</h2>
2929
<ol>
3030
<li><a href="/about/badges">Badges</a>: How to use badges generated by Docs.rs</li>
3131
<li><a href="/about/builds">Builds</a>: How Docs.rs builds documentation for a crate</li>
3232
<li><a href="/about/metadata">Metadata</a>: How you can configure a build</li>
3333
<li><a href="/about/redirections">Redirections</a>: How Docs.rs uses semantic versioning in URLs</li>
3434
</ol>
3535

36-
<h3>Version</h3>
36+
<h3 id="version">Version</h3>
3737
<p>Currently running Docs.rs version is: <strong>{{ docsrs_version() }}</strong></p>
3838

39-
<h3>Contact</h3>
39+
<h3 id="contact">Contact</h3>
4040
{%- set governance_link = "https://www.rust-lang.org/governance/teams/dev-tools#docs-rs" -%}
4141
<p>
4242
Docs.rs is run and maintained by the <a href="{{ governance_link | safe }}">Docs.rs team</a>.

‎templates/core/about/metadata.html

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,11 @@ <h1>Metadata for custom builds</h1>
1616
<pre><code>{%- include "core/Cargo.toml.example" -%}</code></pre>
1717
</div>
1818
{%- endblock body %}
19+
20+
{% block css -%}
21+
{{ macros::highlight_css() }}
22+
{%- endblock css %}
23+
24+
{% block javascript -%}
25+
{{ macros::highlight_js(languages=["ini"]) }}
26+
{%- endblock javascript %}

‎templates/core/about/redirections.html

Lines changed: 58 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -3,58 +3,62 @@
33
{%- block title -%} Shorthand URLs {%- endblock title -%}
44

55
{%- block body -%}
6-
<h1>Shorthand URLs</h1>
7-
<div class="container about">
8-
9-
<p>
10-
Docs.rs uses semver to parse URLs. You can use this feature to access
11-
crates' documentation easily. Example of URL redirections for
12-
<code>clap</code> crate:
13-
</p>
14-
15-
<table class="pure-table pure-table-horizontal">
16-
<thead>
17-
<tr>
18-
<th>URL</th>
19-
<th>Redirects to documentation of</th>
20-
</tr>
21-
</thead>
22-
23-
<tbody>
24-
<tr>
25-
<td><a href="https://docs.rs/clap">docs.rs/clap</a></td>
26-
<td>Latest version of clap</td>
27-
</tr>
28-
29-
<tr>
30-
<td><a href="https://docs.rs/clap/%7E2">docs.rs/clap/~2</a></td>
31-
<td>2.* version</td>
32-
</tr>
33-
34-
<tr>
35-
<td><a href="https://docs.rs/clap/%7E2.9">docs.rs/clap/~2.9</a></td>
36-
<td>2.9.* version</td>
37-
</tr>
38-
39-
<tr>
40-
<td>
41-
<a href="https://docs.rs/clap/2.9.3">docs.rs/clap/2.9.3</a>
42-
</td>
43-
<td>
44-
2.9.3 version (you don't need <code>=</code> unlike semver)
45-
</td>
46-
</tr>
47-
48-
<tr>
49-
<td>
50-
<a href="https://docs.rs/clap/*/clap/struct.App.html">docs.rs/clap/*/clap/struct.App.html</a>
51-
</td>
52-
<td>
53-
Latest version of this page (if it still exists). "latest" or "newest" work as well as
54-
<code>*</code>.
55-
</td>
56-
</tr>
57-
</tbody>
58-
</table>
59-
</div>
6+
<h1>Shorthand URLs</h1>
7+
<div class="container about">
8+
9+
<p>
10+
Docs.rs uses semver to parse URLs. You can use this feature to access
11+
crates' documentation easily. Example of URL redirections for
12+
<code>clap</code> crate:
13+
</p>
14+
15+
<table class="pure-table pure-table-horizontal">
16+
<thead>
17+
<tr>
18+
<th>URL</th>
19+
<th>Redirects to documentation of</th>
20+
</tr>
21+
</thead>
22+
23+
<tbody>
24+
<tr>
25+
<td><a href="https://docs.rs/clap">docs.rs/clap</a></td>
26+
<td>Latest version of clap</td>
27+
</tr>
28+
29+
<tr>
30+
<td>
31+
<a href="https://docs.rs/clap/%7E2">docs.rs/clap/~2</a>
32+
</td>
33+
<td>2.* version</td>
34+
</tr>
35+
36+
<tr>
37+
<td>
38+
<a href="https://docs.rs/clap/%7E2.9">docs.rs/clap/~2.9</a>
39+
</td>
40+
<td>2.9.* version</td>
41+
</tr>
42+
43+
<tr>
44+
<td>
45+
<a href="https://docs.rs/clap/2.9.3">docs.rs/clap/2.9.3</a>
46+
</td>
47+
<td>
48+
2.9.3 version (you don't need <code>=</code> unlike semver)
49+
</td>
50+
</tr>
51+
52+
<tr>
53+
<td>
54+
<a href="https://docs.rs/clap/*/clap/struct.App.html">docs.rs/clap/*/clap/struct.App.html</a>
55+
</td>
56+
<td>
57+
Latest version of this page (if it still exists). "latest" or "newest" work as well as
58+
<code>*</code>.
59+
</td>
60+
</tr>
61+
</tbody>
62+
</table>
63+
</div>
6064
{%- endblock body %}

0 commit comments

Comments
 (0)