LC-3 doctests

[rrbutani]

what

Some of our documentation (mainly lc3-os::trap) is really documenting parts of the LC-3 user interface and we would like to paper over the fact that the underlying doc tests are actually Rust code. It would also be nice to have the run button on examples actually let students run TRAP examples in the tui.

We should:

• make use of doc(alias = "...") to provide some aliases for trap names that users might search for (i.e. println, printf for PUTS, etc.)
• syntax highlight our LC-3 examples correctly
  • not entirely sure what the right way to do this is...
  • code blocks with extra tags (i.e. ARM Assembly,rust) are accepted and still are picked up as doctests by rustdoc but the extra tags have to effect on the formatting
  • for the purposes of the lc3-os crate where we don't have any other doctests we can live with overriding the Rust format definition, globally and: rustdoc does give us hooks to add in our own HTML/CSS
  • but unfortunately — unlike mdbook which uses ace.js and highlights code on the "client side" — rustdoc lexes doc example code and associates tokens with css classes at build time instead of using a JS syntax highligher
  • so we might just be stuck
  • we still can lean on Rust syntax highlighting though so it's not that bad
• have our define macro or something like it wrap our trap examples in the necessary Rust foo to get the examples to actually be run (or if it ends up just being a macro like trap_test! { ... } we can just add the invocations with #s + HALTs at the end, etc.; maybe even assertions to check)
  • there are actually a few options here:
    1. just use our program! style macros
       • this is easy but the downside is that we'd need to be vigilant to not use any of the weird macro syntax (i.e. @ for labels) since this makes it so that run won't work (and nor will copy-pasting examples into an assembler/the TUI)
    2. write the examples as a string passed to the assembler; i.e.:

       # let _a = assemble("
       TRAP 0x36
       # "); 

       • upside here is that we have a guarantee that example is valid LC-3 assembly
       • downside is that... in-editor doc comment syntax highlighting will (correctly) highlight ^ as a string
    3. option 2 but as a (proc?) macro produces the string that's given to the assembler; i.e.:

        # let _a = assemble(lc3_asm_to_string! {
        TRAP 0x36
        # }); 

       • this makes rust-analyzer highlight TRAP 0x36 as it would regular rust code
       • amusingly, rustdoc actually highlights both of these the same way so there's not really a compelling reason to prefer option 3 over option 2
• have the run button on examples send users to web.utp.tools and be able to run and debug their example
  • besides requiring us to put up a version of the web TUI that accepts ?code=... and knows to strip out the # lines, etc.
  • we'd need to set #![doc(html_playground_url = ."..")] in the os crate to get rustdoc to do the thing here

Eventually, when we write some mdbooks for the project, we'll want similar infra (but there we can do this as an mdbook plugin that, for example, picks out code blocks with a tag like LC3, and rewrites them + adds in the LC-3 test wrapping goop; we can also have an editable block and can support highlighting LC3 code correctly ourselves by introducing an ace.js syntax definition for it).

steps

• TBD

where

branch: imp-lc3-doctests

open questions

The above talks about how we might do this but there's still lots to figure out!