My gift to the rustdoc team

81 points by winter

apetros

I am a little surprised that anyone publishing to docs.rs can inject an arbitrary script in there. I am generally in favor of supporting HTML customization and the header-include feature is very cool but this does seem like a reasonable place for a script-src 'self' CSP. There might be other countermeasures I'm not aware of, though (ToS, etc.), and obviously they do have to police malicious crates anyway.

steveklabnik

The canon example of using this behavior is the pwnies crate: https://docs.rs/pwnies/0.0.13/pwnies/
- apetros
  
  I am genuinely conflicted here because... this rules! The web is fun and its capacity for fun customization is one of its great differentiators. We lost a lot when the default expectation for content online was that it had to be presented in a straightjacket. I think we should, as users of the web, push back on that more. People used to learn to code on neopets, not everything needs to be so serious!
  
  On the other hand, as a user of docs.rs, my expectation was not that every crate whose documentation I look up is essentially a fully custom blog. If that is the case—in many ways a very cool, hypermedia-forward approach to structured-but-customizable documentation—that should probably be reflected in the design of the site somehow.
  - apetros
    
    Linking to the robust discussion about this that started in 2017, in case anyone else was curious: https://github.com/rust-lang/docs.rs/issues/167
- weberc2
  
  This made me wonder about other clever uses of doc sites… Could someone effectively host a blog by publishing entries as function comments or similar? Surely someone has thought of this before?
  - tonyfinn
    
    I’ve seen dummy modules used to publish a narrative guide on docs.rs, each file was basically just one long module level doc comment
  - janerik
    
    I built a slide deck using rustdoc once. That should work on docs.rs too
  - zesterer
    
    I sort of already do that for chumsky.
    
    apetros
    
    This is really cool and I wish more rust packages bundled guides of this style.
  - riki
    
    dtolnay's blog seems to be exactly that, though hasn't been updated for a few years.
  - skade
    
    Surely someone has thought of this before?
    
    Yes
  - steveklabnik
    
    Comment removed by author
  - kbknapp
    
    The show notes for the new rustacean podcast were hosted via rustdoc, but not necessarily on crates.io or docs.rs IIRC.
- rplacy
  
  I love the website, a little bear dialog, contents, a self hosted CDN on the same server, awesome work!
  - eaj
    
    You'll probably enjoy the other articles Amos has written about their site, enumerated in this article: https://fasterthanli.me/articles/open-sourcing-the-home-cms
- kornel
  
  Tree-sitter is a surprising case of a C parser not getting rewritten in Rust, even though the project already uses Rust and has first-party packages for it.
  
  For those looking for pure-Rust solutions, there's syntect that implements TextMate/Sublime Text grammars.
  - mousetail
    
    Syntect in theory supports every language supported by Sublime, but in practice it's a huge pain to add any other than the handful included (which excludes typescript) is a huge pain.
    
    First you need to find a sublime plugin. You only need a subset of the files for syntax highlighting but which ones is unclear. You need to clone the entire thing in a place accessible by your program in runtime. Then you need to write code to import it but that section of the module is barely documented and you don't know what file you actually need to find a path to.
    
    The official grammars are bundled into your binary. Want to bundle any other grammars? There's no documentation for it and the functionality is not exposed, so you just need to copy-paste a bunch of syntect code.
    
    Even if you do all this, your new language is still very much a second class citizen, not usable by language detection, not returned in get_lang_by_name type calls which most markdown or html rendering libraries use.
    
    Installing tree-sitter grammars directly from cargo is so much nicer.
    
    kornel
    
    I can't vouch for the docs, but I somehow found what I needed.
    
    You may have missed SyntaxSet? It has all the find_syntax_by_* methods for sniffing by name, extension, first line, tokens, etc. across the entire set (which isn't limited to defaults, it can be built from any set of custom grammars).
    
    There's SyntaxSetBuilder.add_from_folder() that finds all the *.sublime-syntax files it needs, recursively. There's syntect::dumps that can make a precompiled binary dump with all the syntaxes packed together, and can read them back from include_bytes!() so you can have fully self-contained executable without any external files, without parsing YAML at startup. If you enable YAML parser, it still supports into_builder() to add more user-provided grammars at run-time if you need.