Figure out a way to do doctests

[adetaylor]

Right now our documentation code snippets are marked nocompile or use a secret autocxx directive parseonly! so they don't actually do anything. There are two reason:

• We would need a way to feed the C++ code to the include_cpp! macro.
• It will attempt to link lots of test cases into a single executable (as far as I understand it) so if two test cases have C++ types called A (for instance), we will end up with cxx generating all the C ABI interfaces for Rust to interact with A.

The first problem may be solvable using a procedural macro. I don't know exactly how doc tests work, but the aquamarine proc macro clearly does substantial things to doc attributes so we possibly could too (e.g. recognize a special tag for an area of C++ which then gets passed via include_cpp into autocxx-build or something).

I have no good ideas for how to solve the second problem. The best idea I can come up with is to avoid compiling all the C++ code, and instead make weak symbols for all the C symbols which cxx would have generated, which immediately abort. This would prevent users from running the doc tests but would at least fully confirm they compile.

It really bugs me that we can't have fully-functioning code snippets, mixing C++ and Rust, in the docs.

This will get worse with #769 which adds a book.

[adetaylor]

I'm wondering about a proc macro which, like aquamarine's, works on doc attrs.

However its job would be to convert this sort of code:

/// ```
/// /* C++ code:
///     int do_something() {}
/// */
/// include_cpp!(...)
/// fn main() {
///  ffi::do_something()
/// }
/// ```

into something like:

/// ```
/// autocxx::build::try_build("int do_something() {}", parse_quote! {  include_cpp!(...) fn main() {  ffi::do_something() }
/// ```

such that at doctest time, a whole `trybuild` event occurs, creating a separate binary and executing it just like we do for integration tests.

[adetaylor]

OK I figured out how to do this. It's just a bit of work.

1. Specify each code example in the mdbook as a mod like this (note that the snippet starts with three backticks then rust,noplayground).

#[autocxx_doc_test]
mod example {
  static CXX: &str = "inline void do_math() {};";
  use autocxx::prelude::*;
  include_cpp!( /* ... */ )
  fn main() {
     ffi::do_math()
  }
}

2. Implement a new mdbook preprocessor which spots the above and rewrites it to some reasonable markdown documentation, e.g.
   C++:

inline void do_math() {};

Rust:

use autocxx::prelude::*;
include_cpp!( /* ... */ )
fn main() {
  ffi::do_math()
}

3. The #[autocxx_doc_test] macro meanwhile rewrites it instead to be a call to the do_run_test_manual function in our integration-tests, something like this:

do_run_test_manual("inline void do_math() {};", "", quote! {
  use autocxx::prelude::*;
  include_cpp!( /* ... */ )
  fn main() {
    ffi::do_math()
  }
}, None, None);

(possibly this could even be a macro-by-example macro)

I've done some experimentation, and mdbook test sees the code prior to any preprocessors, so this really should work...

It ought to result in each test case running in an independent executable, linked with the C++, just like we have for our integration tests. This should result in a similar situation to the integration tests, where the first doctest to run is super-duper slow because trybuild is busy building all of autocxx's dependencies. But subsequent doctests should be pretty snappy.

The little 'play' button in the mdbook won't work, because it appears to act on the preprocessed code.

[adetaylor]

Something roughly like the above is now done in #769.