Skip to content
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

[WIP] Migrate to Tera for templating #786

Closed
wants to merge 4 commits into from
Closed

Conversation

Kixiron
Copy link
Member

@Kixiron Kixiron commented May 29, 2020

This is an attempt to both remove handlebars and add a type-safe interface to rendering templates while simultaneously making the templates more easy to modify and read.
Template reloading is also added via the very sketchy method of a thread that reloads the templates on 10s intervals, better solutions would be appreciated. (I tried to use notify, but it didn't work on my system even though it's supposed to)

Note: The templates are messy at times (currently), as I've pasted the navigation header into each and edited it to suit the current page, but after everything's done I'll squash them all together into something better
Note: The diff is massive right now because I moved the old templates folder, on the actual release the old templates will be deleted entirely

Pages

  • / => home_page.html
  • /about => about.html
  • /releases, /releases/failures, /releases/recent-failures, /releases/stars => releases.html
  • /releases/feed => release_feed.xml
  • /releases/queue => release_queue.html
  • /crate/:name => crate_details.html
  • /crate/:name/:version/builds => builds.html
  • /releases/activity => release_activity.html
  • /about/metrics => Maybe N/A?
  • /releases/:author
  • /crate/source
  • rustdoc pages

Possible Extensions

  • Graph rendering can be done entirely in Tera as shown in Drawing SVG Graphs with Rust and could be an alternative to Highcharts.js. This has the advantage of even less JavaScript, which makes it more accessible to users and gives us finer-grained control over our graphs, along with being self-sufficient (not relying on another service for part of our site) and not having the highcharts logo that currently exists there
  • Add a footer with relevant info like the other Rust sites do
  • Update highlight.js to the most recent version

Closes #777 and #740

@Kixiron
Copy link
Member Author

Kixiron commented May 29, 2020

Extra ideas: An extra field in the [package.metadata.docs.rs] section can be provided that allows uses to add extra syntax highlighting to their files, for example a C++ interop lib that has lots of example C++ code can put

[package.metadata.docs.rs]
syntax_highlighting = ["cpp"]

in their Cargo.toml and we load the C++ highlight script with their crate. This can be extended further to partially or fully address #302 by offering a subset of further libraries that crates can selectively include

@Kixiron Kixiron linked an issue May 29, 2020 that may be closed by this pull request
@jyn514
Copy link
Member

jyn514 commented May 29, 2020

Let's try to keep refactors separate from added functionality. For instance #777 and all the new features you just suggested should go in a separate PR, that way we can focus on not losing functionality in the change.

@jyn514
Copy link
Member

jyn514 commented May 29, 2020

Template reloading is also added via the very sketchy method of a thread that reloads the templates on 10s intervals, better solutions would be appreciated. (I tried to use notify, but it didn't work on my system even though it's supposed to)

If notify doesn't work I would rather go without hot-reloadint for now.

@Kixiron
Copy link
Member Author

Kixiron commented May 29, 2020

In response to #777, I'm rewriting the templates anyways and it's actually less work to fix the issue because it's just a conditional that's in the header for some reason

@Kixiron Kixiron force-pushed the tera branch 2 times, most recently from 61ca574 to 39e10e5 Compare May 30, 2020 20:19
@Kixiron
Copy link
Member Author

Kixiron commented May 31, 2020

Changes Breakdown:

  • Page is gone, long live models! Templates now correspond directly with a struct in src/web/page/models.rs, which makes templates type-safe, no more guessing if you've got parameters correct and changes are propagated to all call sites
  • All templates are cleanly split up into relevant directories and components, making it easier to add, read, remove and edit (as well as have a coherent theme)
  • handlebars-iron is no longer used as the templating engine of choice, as it has been replaced by tera
  • src/web/page/templates.rs contains the TemplateData struct which holds all loaded templates and any 'global' data that is relevant to all templates (Such as the current version of docs.rs and global alerts)
  • src/web/page/templates.rs also contains some custom functions/filters for tera which allow more logic to be held in the templates themselves instead of the objects passed to them
  • Removed a lot of json tests, they aren't relevant since most everything now uses straight serde derives
  • src/web/page/models.rs contains all renderable structs along with the WebPage trait, which serves as an interface for cleanly manipulating them (e.g. rendering, getting the content type, etc)
  • templates/base.html is the base template from which all (excluding rustdoc) pages inherit, it pulls in style sheets, js and other resources as well as offering blocks where child templates can store data
  • templates/crate contains the crate details, builds and source pages
  • templates/rustdoc contains the rustdoc pages and header
  • templates/releases contains the release queue, stars, recent releases, recent failures, etc. as well as the XML release feed
  • templates/header contains the header that appears on all pages, having the builds/source/crate tabs and global alert as separate components
  • templates/docsrs contains the docs.rs landing page, about page (with the example Cargo.toml separate) and the XML sitemap
  • The arc_swap dependency was added to allow for hot-reloading templates for development flows
  • The --reload option was added to the start-web-server command that activates template hot-reloading

The whole PR is heavily commented, so a lot of diff comes from that. Everything outside of src/web/page/ and templates/ is pretty much unchanged, it's just switching from using Page to using a different struct. Reviewing is probably easiest done by cloning this branch and running it locally before just browsing, everything should work identically to the currently running site

@Kixiron
Copy link
Member Author

Kixiron commented Jun 2, 2020

Laid the groundwork in #805

@Kixiron
Copy link
Member Author

Kixiron commented Jul 13, 2020

Finished by #887 (hopefully)

@Kixiron Kixiron closed this Jul 13, 2020
@Kixiron Kixiron deleted the tera branch July 13, 2020 19:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

No link to builds tab on crate page Switch templating to Tera
2 participants