From ca096f946de70ebeb5a78a68d1319ddc9b317408 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Fri, 31 Jul 2020 19:06:24 -0400 Subject: [PATCH 01/19] [WIP] Split up about page --- src/web/sitemap.rs | 2 +- templates/core/about.html | 201 ------------------------- templates/core/about/badges.html | 45 ++++++ templates/core/about/builds.html | 71 +++++++++ templates/core/about/index.html | 55 +++++++ templates/core/about/metadata.html | 10 ++ templates/core/about/redirections.html | 52 +++++++ 7 files changed, 234 insertions(+), 202 deletions(-) delete mode 100644 templates/core/about.html create mode 100644 templates/core/about/badges.html create mode 100644 templates/core/about/builds.html create mode 100644 templates/core/about/index.html create mode 100644 templates/core/about/metadata.html create mode 100644 templates/core/about/redirections.html diff --git a/src/web/sitemap.rs b/src/web/sitemap.rs index c1944554d..1e7c399ee 100644 --- a/src/web/sitemap.rs +++ b/src/web/sitemap.rs @@ -63,7 +63,7 @@ struct About { limits: Limits, } -impl_webpage!(About = "core/about.html"); +impl_webpage!(About = "core/about/index.html"); pub fn about_handler(req: &mut Request) -> IronResult { let mut conn = extension!(req, Pool).get()?; diff --git a/templates/core/about.html b/templates/core/about.html deleted file mode 100644 index 490c96a2b..000000000 --- a/templates/core/about.html +++ /dev/null @@ -1,201 +0,0 @@ -{% extends "base.html" -%} - -{%- block title -%} About Docs.rs {%- endblock title -%} - -{%- block body -%} - {%- set docsrs_repo = "https://github.com/rust-lang/docs.rs" -%} - -

About Docs.rs

-
-

- Docs.rs (formerly cratesfyi) is an - open source - documentation host for crates of the - Rust Programming Language. -

- -

- Docs.rs automatically builds crates' documentation released on - crates.io - using the nightly release of the Rust compiler. - - {%- if rustc_version %} - The current version of the Rust compiler in use is {{ rustc_version }}. - Builds can take a while depending how many crates are in the queue. - If you need a newer version of this compiler, check the - issues page - and file a new issue if you don't see an existing request. - {%- endif -%} -

- -

- Docs.rs builds crates with environment variable DOCS_RS set to - 1, which enables the crate to detect docs.rs and build the - crate differently for docs. -

- -

- The source code of Docs.rs is available on - GitHub. If - you ever encounter an issue, don't hesitate to report it! (And - thanks in advance!) -

- -

- The README of a crate is taken from the readme field defined in - Cargo.toml. If a crate doesn't have this field, - no README will be displayed. -

- -

Global sandbox limits

- -

- All the builds on docs.rs are executed inside a sandbox with limited - resources. The current limits are the following: -

- - {{ macros::crate_limits(limits=limits) }} - -

- If a build fails because it hit one of those limits please - open an issue - to get them increased for your crate. -

- -

Redirections

- -

- Docs.rs uses semver to parse URLs. You can use this feature to access - crates' documentation easily. Example of URL redirections for - clap crate: -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
URLRedirects to documentation of
docs.rs/clapLatest version of clap
docs.rs/clap/~22.* version
docs.rs/clap/~2.92.9.* version
- docs.rs/clap/2.9.3 - - 2.9.3 version (you don't need = unlike semver) -
- docs.rs/clap/*/clap/struct.App.html - - Latest version of this page (if it still exists). "latest" or "newest" work as well as - *. -
- -

Badges

- -

- You can use badges to show state of your documentation to your users. - The default badge will be pointed at the latest version of a crate. - You can use version parameter to show status of documentation for - any version you want. -

- -

- Badge will display in blue if docs.rs is successfully hosting your crate - documentation, and red if building documentation failing. -

- -

Example badges for mio crate:

- - - - - - - - - - {%- set mio_badge = "https://docs.rs/mio/badge.svg" -%} - - - - - - - - - - - - - - - -
URLBadge
Latest version: {{ mio_badge }}mio
- Version 0.4.4: {{ mio_badge }}?version=0.4.4 - mio
- Version 0.1.0: {{ mio_badge }}?version=0.1.0 - mio
- -

Metadata for custom builds

- -

- You can customize docs.rs builds by defining [package.metadata.docs.rs] - table in your crates' Cargo.toml. -

- -

The available configuration flags you can customize are:

- - 
{%- include "core/Cargo.toml.example" -%}
- -

Test crate documentation build locally

- {%- set build_subcommand = docsrs_repo ~ "/blob/master/README.md#build-subcommand" -%} -

- The docs.rs README describes how to build an - unpublished crate's documentation locally using the same build environment as the build agent. -

- -

Version

-

Currently running Docs.rs version is: {{ docsrs_version() }}

- -

Contact

- {%- set governance_link = "https://www.rust-lang.org/governance/teams/dev-tools#docs-rs" -%} -

- Docs.rs is run and maintained by the Docs.rs team. - You can find us in #docs-rs on Discord. -

- -
-{%- endblock body %} - -{% block css -%} - {{ macros::highlight_css() }} -{%- endblock css %} - -{% block javascript -%} - {{ macros::highlight_js(languages=["ini"]) }} -{%- endblock javascript %} diff --git a/templates/core/about/badges.html b/templates/core/about/badges.html new file mode 100644 index 000000000..25cf6740b --- /dev/null +++ b/templates/core/about/badges.html @@ -0,0 +1,45 @@ +

Badges

+ +

+ You can use badges to show state of your documentation to your users. + The default badge will be pointed at the latest version of a crate. + You can use version parameter to show status of documentation for + any version you want. +

+ +

+ Badge will display in blue if docs.rs is successfully hosting your crate + documentation, and red if building documentation failing. +

+ +

Example badges for mio crate:

+ + + + + + + + + + {%- set mio_badge = "https://docs.rs/mio/badge.svg" -%} + + + + + + + + + + + + + + + +
URLBadge
Latest version: {{ mio_badge }}mio
+ Version 0.4.4: {{ mio_badge }}?version=0.4.4 + mio
+ Version 0.1.0: {{ mio_badge }}?version=0.1.0 + mio
diff --git a/templates/core/about/builds.html b/templates/core/about/builds.html new file mode 100644 index 000000000..c938f0254 --- /dev/null +++ b/templates/core/about/builds.html @@ -0,0 +1,71 @@ +

Builds

+

+ Docs.rs automatically builds crates' documentation released on + crates.io + using the nightly release of the Rust compiler. + Builds can take a while depending how many crates are in the queue. +

+ + {%- if rustc_version %} + The current version of the Rust compiler in use is {{ rustc_version }}. + If you need a newer version of this compiler, check the + issues page + and file a new issue if you don't see an existing request. + {%- endif -%} +

+ +

+ The README of a crate is taken from the readme field defined in + Cargo.toml. If a crate doesn't have this field, + no README will be displayed. +

+ +

Diagnosing a failed build

+ +

Missing dependencies

+

+ Missing dependencies are a common reason for a failed build. + Docs.rs dependencies are managed through https://github.com/rust-lang/crates-build-env; + see https://forge.rust-lang.org/docs-rs/add-dependencies.html for instructions + on how to make a PR. You can always file an issue + if you're having trouble. +

+ +

Detecting Docs.rs from build.rs

+

+ Docs.rs builds crates with the environment variable DOCS_RS set to + 1, which enables the crate to detect docs.rs and build the + crate differently for docs. This can be helpful if you need + dependencies for building the library, but not for building the documentation. +

+ +

Detecting Docs.rs from #[cfg] attributes

+

+ You can detect Docs.rs by having a feature + which is only set by Docs.rs. See Metadata for more information. +

+ +

Global sandbox limits

+ +

+ All the builds on docs.rs are executed inside a sandbox with limited + resources. The current limits are the following: +

+ +{{ macros::crate_limits(limits=limits) }} + +

+ If a build fails because it hit one of those limits please + open an issue + to get them increased for your crate. + Note that network access will not be enabled for any crate. +

+ +

Test crate documentation build locally

+{%- set build_subcommand = docsrs_repo ~ "/blob/master/README.md#build-subcommand" -%} +

+ The docs.rs README describes how to build an + unpublished crate's documentation locally using the same build environment as the build agent. +

+ +

diff --git a/templates/core/about/index.html b/templates/core/about/index.html new file mode 100644 index 000000000..d1fbd40db --- /dev/null +++ b/templates/core/about/index.html @@ -0,0 +1,55 @@ +{% extends "base.html" -%} + +{%- block title -%} About Docs.rs {%- endblock title -%} + +{%- block body -%} + {%- set docsrs_repo = "https://github.com/rust-lang/docs.rs" -%} + +

About Docs.rs

+
+

+ Docs.rs is an + open source + documentation host for crates of the + Rust Programming Language. + All crates published to crates.io + are documented. If you just published a crate, your crate is likely + still in the queue. +

+ +

+ The source code of Docs.rs is available on + GitHub. If + you ever encounter an issue, don't hesitate to report it! (And + thanks in advance!) +

+ + +

More about Docs.rs

+
    +
  1. Builds: How Docs.rs builds documentation for a crate
    2. +
  2. Metadata: How you can configure a build
    3. +
  3. Badges: How to use badges generated by Docs.rs
    4. +
  4. Redirections: How Docs.rs uses semantic versioning in URLs
    5. +
+ +

Version

+

Currently running Docs.rs version is: {{ docsrs_version() }}

+ +

Contact

+ {%- set governance_link = "https://www.rust-lang.org/governance/teams/dev-tools#docs-rs" -%} +

+ Docs.rs is run and maintained by the Docs.rs team. + You can find us in #docs-rs on Discord. +

+ +
+{%- endblock body %} + +{% block css -%} + {{ macros::highlight_css() }} +{%- endblock css %} + +{% block javascript -%} + {{ macros::highlight_js(languages=["ini"]) }} +{%- endblock javascript %} diff --git a/templates/core/about/metadata.html b/templates/core/about/metadata.html new file mode 100644 index 000000000..8d8779b31 --- /dev/null +++ b/templates/core/about/metadata.html @@ -0,0 +1,10 @@ +

Metadata for custom builds

+ +

+ You can customize docs.rs builds by defining [package.metadata.docs.rs] + table in your crates' Cargo.toml. +

+ +

The available configuration flags you can customize are:

+ +
{%- include "core/Cargo.toml.example" -%}
diff --git a/templates/core/about/redirections.html b/templates/core/about/redirections.html new file mode 100644 index 000000000..4f69795a5 --- /dev/null +++ b/templates/core/about/redirections.html @@ -0,0 +1,52 @@ +

Redirections

+ +

+ Docs.rs uses semver to parse URLs. You can use this feature to access + crates' documentation easily. Example of URL redirections for + clap crate: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
URLRedirects to documentation of
docs.rs/clapLatest version of clap
docs.rs/clap/~22.* version
docs.rs/clap/~2.92.9.* version
+ docs.rs/clap/2.9.3 + + 2.9.3 version (you don't need = unlike semver) +
+ docs.rs/clap/*/clap/struct.App.html + + Latest version of this page (if it still exists). "latest" or "newest" work as well as + *. +
From 9b486e288f0b66148918ac24249e3a4f7f1c1e14 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Fri, 31 Jul 2020 20:07:14 -0400 Subject: [PATCH 02/19] Actually serve pages without giving a 404 --- src/web/page/mod.rs | 2 +- src/web/page/web_page.rs | 43 +++++++++++++++++--------- src/web/routes.rs | 2 ++ src/web/sitemap.rs | 42 ++++++++++++++++++++++--- templates/core/about/badges.html | 8 ++++- templates/core/about/builds.html | 20 ++++++++++-- templates/core/about/index.html | 16 +++------- templates/core/about/metadata.html | 8 ++++- templates/core/about/redirections.html | 8 ++++- 9 files changed, 112 insertions(+), 37 deletions(-) diff --git a/src/web/page/mod.rs b/src/web/page/mod.rs index b8a42458e..c97f06d04 100644 --- a/src/web/page/mod.rs +++ b/src/web/page/mod.rs @@ -2,7 +2,7 @@ mod templates; mod web_page; pub(crate) use templates::TemplateData; -pub(crate) use web_page::WebPage; +pub(super) use web_page::{respond, WebPage}; use serde::Serialize; diff --git a/src/web/page/web_page.rs b/src/web/page/web_page.rs index 5c38b76e5..ab0a0c8b5 100644 --- a/src/web/page/web_page.rs +++ b/src/web/page/web_page.rs @@ -26,26 +26,41 @@ macro_rules! impl_webpage { }; } +pub(in crate::web) fn respond( + template: &str, + ctx: Context, + content_type: ContentType, + status: Status, + req: &Request, +) -> IronResult { + let rendered = req + .extensions + .get::() + .expect("missing TemplateData from the request extensions") + .templates + .load() + .render(template, &ctx) + .unwrap(); + + let mut response = Response::with((status, rendered)); + response.headers.set(content_type); + + Ok(response) +} + /// The central trait that rendering pages revolves around, it handles selecting and rendering the template pub trait WebPage: Serialize + Sized { /// Turn the current instance into a `Response`, ready to be served // TODO: We could cache similar pages using the `&Context` fn into_response(self, req: &Request) -> IronResult { let ctx = Context::from_serialize(&self).unwrap(); - - let rendered = req - .extensions - .get::() - .expect("missing TemplateData from the request extensions") - .templates - .load() - .render(Self::TEMPLATE, &ctx) - .unwrap(); - - let mut response = Response::with((self.get_status(), rendered)); - response.headers.set(Self::content_type()); - - Ok(response) + respond( + Self::TEMPLATE, + ctx, + Self::content_type(), + self.get_status(), + req, + ) } /// The name of the template to be rendered diff --git a/src/web/routes.rs b/src/web/routes.rs index a13dff4f6..a7a8d5d21 100644 --- a/src/web/routes.rs +++ b/src/web/routes.rs @@ -23,6 +23,8 @@ pub(super) fn build_routes() -> Routes { routes.internal_page("/about", super::sitemap::about_handler); routes.internal_page("/about/metrics", super::metrics::metrics_handler); + routes.internal_page("/about/builds", super::sitemap::about_builds_handler); + routes.internal_page("/about/:subpage", super::sitemap::about_handler); routes.internal_page("/releases", super::releases::recent_releases_handler); routes.static_resource("/releases/feed", super::releases::releases_feed_handler); diff --git a/src/web/sitemap.rs b/src/web/sitemap.rs index 1e7c399ee..f24b5598d 100644 --- a/src/web/sitemap.rs +++ b/src/web/sitemap.rs @@ -56,16 +56,16 @@ pub fn robots_txt_handler(_: &mut Request) -> IronResult { } #[derive(Debug, Clone, PartialEq, Eq, Serialize)] -struct About { +struct AboutBuilds { /// The current version of rustc that docs.rs is using to build crates rustc_version: Option, /// The default crate build limits limits: Limits, } -impl_webpage!(About = "core/about/index.html"); +impl_webpage!(AboutBuilds = "core/about/builds.html"); -pub fn about_handler(req: &mut Request) -> IronResult { +pub fn about_builds_handler(req: &mut Request) -> IronResult { let mut conn = extension!(req, Pool).get()?; let res = ctry!( req, @@ -80,13 +80,44 @@ pub fn about_handler(req: &mut Request) -> IronResult { } }); - About { + AboutBuilds { rustc_version, limits: Limits::default(), } .into_response(req) } +pub fn about_handler(req: &mut Request) -> IronResult { + use super::page::respond; + use super::ErrorPage; + use iron::status::Status; + + let template = match *req.url.path().last().expect("iron is broken") { + "about" | "index.html" => "index.html", + "badges" => "badges.html", + "metadata" => "metadata.html", + "redirections" => "redirections.html", + _ => { + let msg = "This /about page does not exist. \ + Perhaps you are interested in creating it?"; + let page = ErrorPage { + title: "The requested page does not exist", + message: Some(msg.into()), + status: Status::NotFound, + }; + return page.into_response(req); + } + }; + let template = format!("core/about/{}", template); + respond( + &template, + tera::Context::new(), + ContentType::html(), + Status::Ok, + req, + ) +} + #[cfg(test)] mod tests { use crate::test::{assert_success, wrapper}; @@ -110,6 +141,9 @@ mod tests { fn about_page() { wrapper(|env| { let web = env.frontend(); + for file in std::fs::read_dir("templates/core/about")? { + assert_success(path?, web)?; + } assert_success("/about", web) }) } diff --git a/templates/core/about/badges.html b/templates/core/about/badges.html index 25cf6740b..fbb6b530d 100644 --- a/templates/core/about/badges.html +++ b/templates/core/about/badges.html @@ -1,4 +1,9 @@ -

Badges

+{% extends "base.html" -%} + +{%- block title -%} Badges {%- endblock title -%} + +{%- block body -%} +

Badges

You can use badges to show state of your documentation to your users. @@ -43,3 +48,4 @@

Badges

+{%- endblock body %} diff --git a/templates/core/about/builds.html b/templates/core/about/builds.html index c938f0254..116ec1d64 100644 --- a/templates/core/about/builds.html +++ b/templates/core/about/builds.html @@ -1,4 +1,10 @@ -

Builds

+{% extends "base.html" -%} + +{%- block title -%} Builds {%- endblock title -%} + +{%- block body -%} +{%- set docsrs_repo = "https://github.com/rust-lang/docs.rs" -%} +

Builds

Docs.rs automatically builds crates' documentation released on crates.io @@ -42,7 +48,7 @@

Detecting Docs.rs from build.rs

Detecting Docs.rs from #[cfg] attributes

You can detect Docs.rs by having a feature - which is only set by Docs.rs. See Metadata for more information. + which is only set by Docs.rs. See Metadata for more information.

Global sandbox limits

@@ -68,4 +74,12 @@

Test crate documentation build locally

unpublished crate's documentation locally using the same build environment as the build agent.

-

+{%- endblock body %} + +{% block css -%} + {{ macros::highlight_css() }} +{%- endblock css %} + +{% block javascript -%} + {{ macros::highlight_js(languages=["ini"]) }} +{%- endblock javascript %} diff --git a/templates/core/about/index.html b/templates/core/about/index.html index d1fbd40db..d8ba94af3 100644 --- a/templates/core/about/index.html +++ b/templates/core/about/index.html @@ -27,10 +27,10 @@

About Docs.rs

More about Docs.rs

    -
  1. Builds: How Docs.rs builds documentation for a crate
    2. -
  2. Metadata: How you can configure a build
    3. -
  3. Badges: How to use badges generated by Docs.rs
    4. -
  4. Redirections: How Docs.rs uses semantic versioning in URLs
    5. +
  5. Builds: How Docs.rs builds documentation for a crate
    6. +
  6. Metadata: How you can configure a build
    7. +
  7. Badges: How to use badges generated by Docs.rs
    8. +
  8. Redirections: How Docs.rs uses semantic versioning in URLs

Version

@@ -45,11 +45,3 @@

Contact

{%- endblock body %} - -{% block css -%} - {{ macros::highlight_css() }} -{%- endblock css %} - -{% block javascript -%} - {{ macros::highlight_js(languages=["ini"]) }} -{%- endblock javascript %} diff --git a/templates/core/about/metadata.html b/templates/core/about/metadata.html index 8d8779b31..146df523c 100644 --- a/templates/core/about/metadata.html +++ b/templates/core/about/metadata.html @@ -1,4 +1,9 @@ -

Metadata for custom builds

+{% extends "base.html" -%} + +{%- block title -%} Metadata {%- endblock title -%} + +{%- block body -%} +

Metadata for custom builds

You can customize docs.rs builds by defining [package.metadata.docs.rs] @@ -8,3 +13,4 @@

Metadata for custom builds

The available configuration flags you can customize are:

{%- include "core/Cargo.toml.example" -%}
+{%- endblock body %} diff --git a/templates/core/about/redirections.html b/templates/core/about/redirections.html index 4f69795a5..ccbad32a8 100644 --- a/templates/core/about/redirections.html +++ b/templates/core/about/redirections.html @@ -1,4 +1,9 @@ -

Redirections

+{% extends "base.html" -%} + +{%- block title -%} Redirections {%- endblock title -%} + +{%- block body -%} +

Redirections

Docs.rs uses semver to parse URLs. You can use this feature to access @@ -50,3 +55,4 @@

Redirections

+{%- endblock body %} From 9a5b7f8f5e65dcd470cb44556439fb87e4cc3095 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Fri, 31 Jul 2020 20:18:48 -0400 Subject: [PATCH 03/19] Fix tests --- src/web/sitemap.rs | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/src/web/sitemap.rs b/src/web/sitemap.rs index f24b5598d..fc9b4e978 100644 --- a/src/web/sitemap.rs +++ b/src/web/sitemap.rs @@ -142,7 +142,17 @@ mod tests { wrapper(|env| { let web = env.frontend(); for file in std::fs::read_dir("templates/core/about")? { - assert_success(path?, web)?; + use std::ffi::OsStr; + + let file_path = file?.path(); + if file_path.extension() != Some(OsStr::new("html")) + || file_path.file_stem() == Some(OsStr::new("index")) + { + continue; + } + let filename = file_path.file_stem().unwrap().to_str().unwrap(); + let path = format!("/about/{}", filename); + assert_success(&path, web)?; } assert_success("/about", web) }) From 05f60c370c131df115114bcaae579ace7cff2177 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sat, 1 Aug 2020 12:35:40 -0400 Subject: [PATCH 04/19] Don't recompile every time a template file is changed --- build.rs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/build.rs b/build.rs index 907df3ff0..30c3ca369 100644 --- a/build.rs +++ b/build.rs @@ -11,6 +11,14 @@ fn main() { env::var("TARGET").unwrap() ); + // Don't rerun anytime a single change is made + println!("cargo:rerun-if-changed=templates/style.scss"); + println!("cargo:rerun-if-changed=templates/menu.js"); + println!("cargo:rerun-if-changed=templates/index.js"); + // TODO: are these right? + println!("cargo:rerun-if-changed=.git/HEAD"); + println!("cargo:rerun-if-changed=.git/index"); + write_git_version(); compile_sass(); copy_js(); From fec02beb025a36639aae254ba2fffdb7e3888083 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sat, 1 Aug 2020 12:36:06 -0400 Subject: [PATCH 05/19] Add crappy header bar --- templates/about-base.html | 10 ++++++++++ templates/core/about/badges.html | 2 +- templates/core/about/builds.html | 2 +- templates/core/about/index.html | 2 +- templates/core/about/metadata.html | 2 +- templates/core/about/redirections.html | 2 +- 6 files changed, 15 insertions(+), 5 deletions(-) create mode 100644 templates/about-base.html diff --git a/templates/about-base.html b/templates/about-base.html new file mode 100644 index 000000000..0250c5b70 --- /dev/null +++ b/templates/about-base.html @@ -0,0 +1,10 @@ +{% extends "base.html" %} +{% block header %} + +{% endblock %} diff --git a/templates/core/about/badges.html b/templates/core/about/badges.html index fbb6b530d..0d6f38194 100644 --- a/templates/core/about/badges.html +++ b/templates/core/about/badges.html @@ -1,4 +1,4 @@ -{% extends "base.html" -%} +{% extends "about-base.html" -%} {%- block title -%} Badges {%- endblock title -%} diff --git a/templates/core/about/builds.html b/templates/core/about/builds.html index 116ec1d64..d015e6676 100644 --- a/templates/core/about/builds.html +++ b/templates/core/about/builds.html @@ -1,4 +1,4 @@ -{% extends "base.html" -%} +{% extends "about-base.html" -%} {%- block title -%} Builds {%- endblock title -%} diff --git a/templates/core/about/index.html b/templates/core/about/index.html index d8ba94af3..6bb256221 100644 --- a/templates/core/about/index.html +++ b/templates/core/about/index.html @@ -1,4 +1,4 @@ -{% extends "base.html" -%} +{% extends "about-base.html" -%} {%- block title -%} About Docs.rs {%- endblock title -%} diff --git a/templates/core/about/metadata.html b/templates/core/about/metadata.html index 146df523c..b3bd7259f 100644 --- a/templates/core/about/metadata.html +++ b/templates/core/about/metadata.html @@ -1,4 +1,4 @@ -{% extends "base.html" -%} +{% extends "about-base.html" -%} {%- block title -%} Metadata {%- endblock title -%} diff --git a/templates/core/about/redirections.html b/templates/core/about/redirections.html index ccbad32a8..e471b428e 100644 --- a/templates/core/about/redirections.html +++ b/templates/core/about/redirections.html @@ -1,4 +1,4 @@ -{% extends "base.html" -%} +{% extends "about-base.html" -%} {%- block title -%} Redirections {%- endblock title -%} From b85cefe3f5ff6037528a59ff529109391a9b0850 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sat, 1 Aug 2020 12:46:54 -0400 Subject: [PATCH 06/19] Try to make it less ugly --- templates/about-base.html | 20 ++++--- templates/core/about/badges.html | 2 + templates/core/about/builds.html | 20 ++++--- templates/core/about/index.html | 82 +++++++++++++------------- templates/core/about/metadata.html | 2 + templates/core/about/redirections.html | 2 + 6 files changed, 72 insertions(+), 56 deletions(-) diff --git a/templates/about-base.html b/templates/about-base.html index 0250c5b70..53273a13e 100644 --- a/templates/about-base.html +++ b/templates/about-base.html @@ -1,10 +1,16 @@ {% extends "base.html" %} {% block header %} - +
+
+
+ +
+
+
{% endblock %} diff --git a/templates/core/about/badges.html b/templates/core/about/badges.html index 0d6f38194..47deb619e 100644 --- a/templates/core/about/badges.html +++ b/templates/core/about/badges.html @@ -5,6 +5,7 @@ {%- block body -%}

Badges

+

You can use badges to show state of your documentation to your users. The default badge will be pointed at the latest version of a crate. @@ -48,4 +49,5 @@

Badges

+
{%- endblock body %} diff --git a/templates/core/about/builds.html b/templates/core/about/builds.html index d015e6676..1243c3ddb 100644 --- a/templates/core/about/builds.html +++ b/templates/core/about/builds.html @@ -5,13 +5,15 @@ {%- block body -%} {%- set docsrs_repo = "https://github.com/rust-lang/docs.rs" -%}

Builds

-

- Docs.rs automatically builds crates' documentation released on - crates.io - using the nightly release of the Rust compiler. - Builds can take a while depending how many crates are in the queue. -

+
+

+ Docs.rs automatically builds crates' documentation released on + crates.io + using the nightly release of the Rust compiler. + Builds can take a while depending how many crates are in the queue. +

+

{%- if rustc_version %} The current version of the Rust compiler in use is {{ rustc_version }}. If you need a newer version of this compiler, check the @@ -31,8 +33,9 @@

Diagnosing a failed build

Missing dependencies

Missing dependencies are a common reason for a failed build. - Docs.rs dependencies are managed through https://github.com/rust-lang/crates-build-env; - see https://forge.rust-lang.org/docs-rs/add-dependencies.html for instructions + Docs.rs dependencies are managed through + crates-build-env; + see Forge for instructions on how to make a PR. You can always file an issue if you're having trouble.

@@ -73,6 +76,7 @@

Test crate documentation build locally

The docs.rs README describes how to build an unpublished crate's documentation locally using the same build environment as the build agent.

+
{%- endblock body %} diff --git a/templates/core/about/index.html b/templates/core/about/index.html index 6bb256221..d3d695599 100644 --- a/templates/core/about/index.html +++ b/templates/core/about/index.html @@ -3,45 +3,45 @@ {%- block title -%} About Docs.rs {%- endblock title -%} {%- block body -%} - {%- set docsrs_repo = "https://github.com/rust-lang/docs.rs" -%} - -

About Docs.rs

-
-

- Docs.rs is an - open source - documentation host for crates of the - Rust Programming Language. - All crates published to crates.io - are documented. If you just published a crate, your crate is likely - still in the queue. -

- -

- The source code of Docs.rs is available on - GitHub. If - you ever encounter an issue, don't hesitate to report it! (And - thanks in advance!) -

- - -

More about Docs.rs

-
    -
  1. Builds: How Docs.rs builds documentation for a crate
    2. -
  2. Metadata: How you can configure a build
    3. -
  3. Badges: How to use badges generated by Docs.rs
    4. -
  4. Redirections: How Docs.rs uses semantic versioning in URLs
    5. -
- -

Version

-

Currently running Docs.rs version is: {{ docsrs_version() }}

- -

Contact

- {%- set governance_link = "https://www.rust-lang.org/governance/teams/dev-tools#docs-rs" -%} -

- Docs.rs is run and maintained by the Docs.rs team. - You can find us in #docs-rs on Discord. -

- -
+{%- set docsrs_repo = "https://github.com/rust-lang/docs.rs" -%} + +

About Docs.rs

+
+

+ Docs.rs is an + open source + documentation host for crates of the + Rust Programming Language. + All crates published to crates.io + are documented. If you just published a crate, your crate is likely + still in the queue. +

+ +

+ The source code of Docs.rs is available on + GitHub. If + you ever encounter an issue, don't hesitate to report it! (And + thanks in advance!) +

+ + +

More about Docs.rs

+
    +
  1. Badges: How to use badges generated by Docs.rs
    2. +
  2. Builds: How Docs.rs builds documentation for a crate
    3. +
  3. Metadata: How you can configure a build
    4. +
  4. Redirections: How Docs.rs uses semantic versioning in URLs
    5. +
+ +

Version

+

Currently running Docs.rs version is: {{ docsrs_version() }}

+ +

Contact

+ {%- set governance_link = "https://www.rust-lang.org/governance/teams/dev-tools#docs-rs" -%} +

+ Docs.rs is run and maintained by the Docs.rs team. + You can find us in #docs-rs on Discord. +

+ +
{%- endblock body %} diff --git a/templates/core/about/metadata.html b/templates/core/about/metadata.html index b3bd7259f..d090d6797 100644 --- a/templates/core/about/metadata.html +++ b/templates/core/about/metadata.html @@ -5,6 +5,7 @@ {%- block body -%}

Metadata for custom builds

+

You can customize docs.rs builds by defining [package.metadata.docs.rs] table in your crates' Cargo.toml. @@ -13,4 +14,5 @@

Metadata for custom builds

The available configuration flags you can customize are:

{%- include "core/Cargo.toml.example" -%}
+
{%- endblock body %} diff --git a/templates/core/about/redirections.html b/templates/core/about/redirections.html index e471b428e..636d88359 100644 --- a/templates/core/about/redirections.html +++ b/templates/core/about/redirections.html @@ -4,6 +4,7 @@ {%- block body -%}

Redirections

+

Docs.rs uses semver to parse URLs. You can use this feature to access @@ -55,4 +56,5 @@

Redirections

+
{%- endblock body %} From d974c404082a65f666dca2df8260fc1e7b9d98f0 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sat, 1 Aug 2020 14:10:07 -0400 Subject: [PATCH 07/19] Remove `fn respond()` and allow dynamically calculating a template --- src/web/page/mod.rs | 2 +- src/web/page/web_page.rs | 52 ++++++++++++++++------------------------ src/web/sitemap.rs | 35 ++++++++++++++++----------- 3 files changed, 43 insertions(+), 46 deletions(-) diff --git a/src/web/page/mod.rs b/src/web/page/mod.rs index c97f06d04..d6d68c1d4 100644 --- a/src/web/page/mod.rs +++ b/src/web/page/mod.rs @@ -2,7 +2,7 @@ mod templates; mod web_page; pub(crate) use templates::TemplateData; -pub(super) use web_page::{respond, WebPage}; +pub(super) use web_page::WebPage; use serde::Serialize; diff --git a/src/web/page/web_page.rs b/src/web/page/web_page.rs index ab0a0c8b5..b66e608ff 100644 --- a/src/web/page/web_page.rs +++ b/src/web/page/web_page.rs @@ -1,14 +1,20 @@ use super::TemplateData; use iron::{headers::ContentType, response::Response, status::Status, IronResult, Request}; use serde::Serialize; +use std::borrow::Cow; use tera::Context; /// When making using a custom status, use a closure that coerces to a `fn(&Self) -> Status` #[macro_export] macro_rules! impl_webpage { + ($page:ty = $template:literal $(, status = $status:expr)? $(, content_type = $content_type:expr)? $(,)?) => { + impl_webpage!($page = |_| ::std::borrow::Cow::Borrowed($template) $(, status = $status)? $(, content_type = $content_type)?); + }; ($page:ty = $template:expr $(, status = $status:expr)? $(, content_type = $content_type:expr)? $(,)?) => { impl $crate::web::page::WebPage for $page { - const TEMPLATE: &'static str = $template; + fn template(&self) -> ::std::borrow::Cow<'static, str> { + $template(self) + } $( fn get_status(&self) -> ::iron::status::Status { @@ -26,45 +32,29 @@ macro_rules! impl_webpage { }; } -pub(in crate::web) fn respond( - template: &str, - ctx: Context, - content_type: ContentType, - status: Status, - req: &Request, -) -> IronResult { - let rendered = req - .extensions - .get::() - .expect("missing TemplateData from the request extensions") - .templates - .load() - .render(template, &ctx) - .unwrap(); - - let mut response = Response::with((status, rendered)); - response.headers.set(content_type); - - Ok(response) -} - /// The central trait that rendering pages revolves around, it handles selecting and rendering the template pub trait WebPage: Serialize + Sized { /// Turn the current instance into a `Response`, ready to be served // TODO: We could cache similar pages using the `&Context` fn into_response(self, req: &Request) -> IronResult { let ctx = Context::from_serialize(&self).unwrap(); - respond( - Self::TEMPLATE, - ctx, - Self::content_type(), - self.get_status(), - req, - ) + let rendered = req + .extensions + .get::() + .expect("missing TemplateData from the request extensions") + .templates + .load() + .render(&self.template(), &ctx) + .unwrap(); + + let mut response = Response::with((self.get_status(), rendered)); + response.headers.set(Self::content_type()); + + Ok(response) } /// The name of the template to be rendered - const TEMPLATE: &'static str; + fn template(&self) -> Cow<'static, str>; /// Gets the status of the request, defaults to `Ok` fn get_status(&self) -> Status { diff --git a/src/web/sitemap.rs b/src/web/sitemap.rs index fc9b4e978..46a751463 100644 --- a/src/web/sitemap.rs +++ b/src/web/sitemap.rs @@ -61,6 +61,8 @@ struct AboutBuilds { rustc_version: Option, /// The default crate build limits limits: Limits, + /// Just for the template, since this isn't shared with AboutPage + active_tab: &'static str, } impl_webpage!(AboutBuilds = "core/about/builds.html"); @@ -83,20 +85,27 @@ pub fn about_builds_handler(req: &mut Request) -> IronResult { AboutBuilds { rustc_version, limits: Limits::default(), + active_tab: "builds", } .into_response(req) } +#[derive(Serialize)] +struct AboutPage<'a> { + #[serde(skip)] + template: String, + active_tab: &'a str, +} + +impl_webpage!(AboutPage<'_> = |this: &AboutPage| this.template.clone().into()); + pub fn about_handler(req: &mut Request) -> IronResult { - use super::page::respond; use super::ErrorPage; use iron::status::Status; - let template = match *req.url.path().last().expect("iron is broken") { - "about" | "index.html" => "index.html", - "badges" => "badges.html", - "metadata" => "metadata.html", - "redirections" => "redirections.html", + let name = match *req.url.path().last().expect("iron is broken") { + "about" | "index" => "index", + x @ "badges" | x @ "metadata" | x @ "redirections" => x, _ => { let msg = "This /about page does not exist. \ Perhaps you are interested in creating it?"; @@ -108,14 +117,12 @@ pub fn about_handler(req: &mut Request) -> IronResult { return page.into_response(req); } }; - let template = format!("core/about/{}", template); - respond( - &template, - tera::Context::new(), - ContentType::html(), - Status::Ok, - req, - ) + let template = format!("core/about/{}.html", name); + AboutPage { + template, + active_tab: name, + } + .into_response(req) } #[cfg(test)] From e1047ced976249de7f67828b3824dbc508ae676d Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sat, 1 Aug 2020 14:10:37 -0400 Subject: [PATCH 08/19] Make the links prettier --- templates/about-base.html | 13 +++++++------ templates/macros.html | 8 ++++++++ 2 files changed, 15 insertions(+), 6 deletions(-) diff --git a/templates/about-base.html b/templates/about-base.html index 53273a13e..bb3df96b2 100644 --- a/templates/about-base.html +++ b/templates/about-base.html @@ -1,14 +1,15 @@ {% extends "base.html" %} {% block header %}
-
+
+

Docs.rs documentation

    -
  • About
    • -
  • Badges
    • -
  • Builds
    • -
  • Metadata
    • -
  • Redirections
    • + {{ macros::active_link(expected="index", href="/about", text="About") }} + {{ macros::active_link(expected="badges", href="/about/badges", text="Badges") }} + {{ macros::active_link(expected="builds", href="/about/builds", text="Builds") }} + {{ macros::active_link(expected="metadata", href="/about/metadata", text="Metadata") }} + {{ macros::active_link(expected="redirections", href="/about/redirections", text="Redirections") }}
diff --git a/templates/macros.html b/templates/macros.html index b51f26cdf..ee5507b3b 100644 --- a/templates/macros.html +++ b/templates/macros.html @@ -2,6 +2,14 @@ Makes the appropriate JS imports for highlighting * `languages` An array of strings where each is a valid highlight.js language #} +{% macro active_link(expected, href, text) %} +
  • + + {{ text }} + +
    • +{% endmacro active_link %} + {% macro highlight_js(languages) %} {# Load the highlight script #}