DOC: more context in embedded code

Fixes #2816
DOC: more robust compilation and CSS