Add embedded compiler-explorer example

[cz4rs]

This is not mergeable, just providing actual examples for the next documentation session.

Sphinx allows for html injection with .. raw:: html. That's probably the easiest way to use Share -> Embed in iframe functionality available in compiler-explorer.

See initialization example below (our current approach is kept for comparison):

Code used:

.. raw:: html

  <iframe width="800px" height="300px" src="https://godbolt.org/e?hideEditorToolbars=true#g:!((g:!((g:!((h:codeEditor,i:(filename:'1',fontScale:14,fontUsePx:'0',j:1,lang:c%2B%2B,selection:(endColumn:1,endLineNumber:9,positionColumn:1,positionLineNumber:9,selectionStartColumn:1,selectionStartLineNumber:9,startColumn:1,startLineNumber:9),source:'%23include+%3CKokkos_Core.hpp%3E%0A%0Aint+main(int+argc,+char**+argv)+%7B%0A++Kokkos::initialize(argc,+argv)%3B%0A++Kokkos::View%3Cdouble*%3E+my_view(%22my_view%22,+10)%3B%0A++Kokkos::finalize()%3B%0A++//+my_view+destructor+called+after+Kokkos::finalize+!!%0A%7D%0A'),l:'5',n:'0',o:'C%2B%2B+source+%231',t:'0')),k:50,l:'4',m:100,n:'0',o:'',s:0,t:'0'),(g:!((h:compiler,i:(compiler:clang1600,deviceViewOpen:'1',filters:(b:'0',binary:'1',binaryObject:'1',commentOnly:'0',debugCalls:'1',demangle:'0',directives:'0',execute:'1',intel:'0',libraryCode:'0',trim:'1'),flagsViewOpen:'1',fontScale:14,fontUsePx:'0',j:1,lang:c%2B%2B,libs:!((name:kokkos,ver:'4100')),options:'',overrides:!(),selection:(endColumn:1,endLineNumber:1,positionColumn:1,positionLineNumber:1,selectionStartColumn:1,selectionStartLineNumber:1,startColumn:1,startLineNumber:1),source:1),l:'5',n:'0',o:'+x86-64+clang+16.0.0+(Editor+%231)',t:'0')),header:(),k:50,l:'4',n:'0',o:'',s:0,t:'0')),l:'2',n:'0',o:'',t:'0')),version:4"></iframe>

Note: there is some customization available when generating the link (Read only, Hide editor toolbars). Further configuration is contained in the generated link.

[cz4rs]

Another way to enforce that the code snippets in documentation are compiling: literal include (2e525e9).
If we supplement this with an autogenerated Edit on Compiler Explorer button, we might have a quicker, more lightweight option than embedding CE directly.

[crtrott]

Hm, interesting, I was thinking of much simpler: i.e. have a code snippet and then a short link to godbolt. Obviously that wouldn't guarantee that they are the same thing.

[ajpowelsnl]

TODO:

• Cezary: Fix up example for Wed. meeting to demo for the team
• Discuss in Wed. meeting if we want Compiler Explorer (CE) examples to simply compile, or also generate run-able executable;
  • Simple CE examples (for Documentation, etc.) into existing or new repos?
  • Integrate CE examples into training, teaching & demos?

[cz4rs]

code-block above + a manually created shortlink to Compiler Explorer:

[cz4rs]

helo_world_lambda.cpp + an auto-generated link using clientstate API:

See live version.

See ceinclude.py for extension details.

[masterleinad]

Given the number of comments in this file, I would rather not include that one specifically. Other than that, it's a good idea to use examples we run through our CI. I could see that we just reduce the verbosity in these files and refer to kokkos-tutorials for more extensive tutorials.

[ajpowelsnl]

@cz4rs , @masterleinad - What do we need to do next to work towards completion of this issue?

[cz4rs]

@cz4rs , @masterleinad - What do we need to do next to work towards completion of this issue?

Hi @ajpowelsnl! As far as I know there was no decision (or even major discussion) regarding how much integration and how many changes we want to do.

Assuming we just want to update existing snippets with Edit on Compiler Explorer button, we have two options:

• add manually created shortlinks - Add embedded compiler-explorer example #444 (comment)
  • not great, not terrible - this approach involves manual work and the shortlinks are permanent so we have to remember to update them
• add auto-generated links - Add embedded compiler-explorer example #444 (comment)
  • replace .. code-block:: cpp with our custom extension (e.g. .. ce-code-block:: cpp) that will wrap the code-block and add Compiler Explorer link
  • this extension will be similar to the ceinclude.py from this PR, only based on code-block instead of literalinclude

IMHO the second option is clearly better (less maintenance!), with the only downside being that the generated links are quite long and ugly:

https://godbolt.org/clientstate/eyJzZXNzaW9ucyI6IFt7ImlkIjogMSwgImxhbmd1YWdlIjogImMrKyIsICJzb3VyY2UiOiAiLy9ASEVBREVSXG4vLyAqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKipcbi8vXG4vLyAgICAgICAgICAgICAgICAgICAgICAgIEtva2tvcyB2LiA0LjBcbi8vICAgICAgIENvcHlyaWdodCAoMjAyMikgTmF0aW9uYWwgVGVjaG5vbG9neSAmIEVuZ2luZWVyaW5nXG4vLyAgICAgICAgICAgICAgIFNvbHV0aW9ucyBvZiBTYW5kaWEsIExMQyAoTlRFU1MpLlxuLy9cbi8vIFVuZGVyIHRoZSB0ZXJtcyBvZiBDb250cmFjdCBERS1OQTAwMDM1MjUgd2l0aCBOVEVTUyxcbi8vIHRoZSBVLlMuIEdvdmVybm1lbnQgcmV0YWlucyBjZXJ0YWluIHJpZ2h0cyBpbiB0aGlzIHNvZnR3YXJlLlxuLy9cbi8vIFBhcnQgb2YgS29ra29zLCB1bmRlciB0aGUgQXBhY2hlIExpY2Vuc2UgdjIuMCB3aXRoIExMVk0gRXhjZXB0aW9ucy5cbi8vIFNlZSBodHRwczovL2tva2tvcy5vcmcvTElDRU5TRSBmb3IgbGljZW5zZSBpbmZvcm1hdGlvbi5cbi8vIFNQRFgtTGljZW5zZS1JZGVudGlmaWVyOiBBcGFjaGUtMi4wIFdJVEggTExWTS1leGNlcHRpb25cbi8vXG4vL0BIRUFERVJcblxuI2luY2x1ZGUgPEtva2tvc19Db3JlLmhwcD5cbiNpbmNsdWRlIDxjc3RkaW8-XG4jaW5jbHVkZSA8dHlwZWluZm8-XG5cbi8vXG4vLyBcIkhlbGxvIHdvcmxkXCIgcGFyYWxsZWxfZm9yIGV4YW1wbGU6XG4vLyAgIDEuIFN0YXJ0IHVwIEtva2tvc1xuLy8gICAyLiBFeGVjdXRlIGEgcGFyYWxsZWwgZm9yIGxvb3AgaW4gdGhlIGRlZmF1bHQgZXhlY3V0aW9uIHNwYWNlLFxuLy8gICAgICB1c2luZyBhIEMrKzExIGxhbWJkYSB0byBkZWZpbmUgdGhlIGxvb3AgYm9keVxuLy8gICAzLiBTaHV0IGRvd24gS29ra29zXG4vL1xuLy8gVGhpcyBleGFtcGxlIG9ubHkgYnVpbGRzIGlmIEMrKzExIGlzIGVuYWJsZWQuICBDb21wYXJlIHRoaXMgZXhhbXBsZVxuLy8gdG8gMDFfaGVsbG9fd29ybGQsIHdoaWNoIHVzZXMgZnVuY3RvcnMgKGV4cGxpY2l0bHkgZGVmaW5lZCBjbGFzc2VzKVxuLy8gdG8gZGVmaW5lIHRoZSBsb29wIGJvZHkgb2YgdGhlIHBhcmFsbGVsX2Zvci4gIEJvdGggZnVuY3RvcnMgYW5kXG4vLyBsYW1iZGFzIGhhdmUgdGhlaXIgcGxhY2VzLlxuLy9cblxuaW50IG1haW4oaW50IGFyZ2MsIGNoYXIqIGFyZ3ZbXSkge1xuICAvLyBZb3UgbXVzdCBjYWxsIGluaXRpYWxpemUoKSBiZWZvcmUgeW91IG1heSBjYWxsIEtva2tvcy5cbiAgLy9cbiAgLy8gV2l0aCBubyBhcmd1bWVudHMsIHRoaXMgaW5pdGlhbGl6ZXMgdGhlIGRlZmF1bHQgZXhlY3V0aW9uIHNwYWNlXG4gIC8vIChhbmQgcG90ZW50aWFsbHkgaXRzIGhvc3QgZXhlY3V0aW9uIHNwYWNlKSB3aXRoIGRlZmF1bHRcbiAgLy8gcGFyYW1ldGVycy4gIFlvdSBtYXkgYWxzbyBwYXNzIGluIGFyZ2MgYW5kIGFyZ3YsIGFuYWxvZ291c2x5IHRvXG4gIC8vIE1QSV9Jbml0KCkuICBJdCByZWFkcyBhbmQgcmVtb3ZlcyBjb21tYW5kLWxpbmUgYXJndW1lbnRzIHRoYXRcbiAgLy8gc3RhcnQgd2l0aCBcIi0ta29ra29zLVwiLlxuICBLb2trb3M6OmluaXRpYWxpemUoYXJnYywgYXJndik7XG5cbiAgLy8gUHJpbnQgdGhlIG5hbWUgb2YgS29ra29zJyBkZWZhdWx0IGV4ZWN1dGlvbiBzcGFjZS4gIFdlJ3JlIHVzaW5nXG4gIC8vIHR5cGVpZCBoZXJlLCBzbyB0aGUgbmFtZSBtaWdodCBnZXQgYSBiaXQgbWFuZ2xlZCBieSB0aGUgbGlua2VyLFxuICAvLyBidXQgeW91IHNob3VsZCBzdGlsbCBiZSBhYmxlIHRvIGZpZ3VyZSBvdXQgd2hhdCBpdCBpcy5cbiAgcHJpbnRmKFwiSGVsbG8gV29ybGQgb24gS29ra29zIGV4ZWN1dGlvbiBzcGFjZSAlc1xcblwiLFxuICAgICAgICAgdHlwZWlkKEtva2tvczo6RGVmYXVsdEV4ZWN1dGlvblNwYWNlKS5uYW1lKCkpO1xuXG4gIC8vIFJ1biBsYW1iZGEgb24gdGhlIGRlZmF1bHQgS29ra29zIGV4ZWN1dGlvbiBzcGFjZSBpbiBwYXJhbGxlbCxcbiAgLy8gd2l0aCBhIHBhcmFsbGVsIGZvciBsb29wIGNvdW50IG9mIDE1LiAgVGhlIGxhbWJkYSdzIGFyZ3VtZW50IGlzXG4gIC8vIGFuIGludGVnZXIgd2hpY2ggaXMgdGhlIHBhcmFsbGVsIGZvcidzIGxvb3AgaW5kZXguICBBcyB5b3UgbGVhcm5cbiAgLy8gYWJvdXQgZGlmZmVyZW50IGtpbmRzIG9mIHBhcmFsbGVsaXNtLCB5b3Ugd2lsbCBmaW5kIG91dCB0aGF0XG4gIC8vIHRoZXJlIGFyZSBvdGhlciB2YWxpZCBhcmd1bWVudCB0eXBlcyBhcyB3ZWxsLlxuICAvL1xuICAvLyBGb3IgYSBzaW5nbGUgbGV2ZWwgb2YgcGFyYWxsZWxpc20sIHdlIHByZWZlciB0aGF0IHlvdSB1c2UgdGhlXG4gIC8vIEtPS0tPU19MQU1CREEgbWFjcm8uICBJZiBDVURBIGlzIGRpc2FibGVkLCB0aGlzIGp1c3QgdHVybnMgaW50b1xuICAvLyBbPV0uICBUaGF0IGNhcHR1cmVzIHZhcmlhYmxlcyBmcm9tIHRoZSBzdXJyb3VuZGluZyBzY29wZSBieVxuICAvLyB2YWx1ZS4gIERvIE5PVCBjYXB0dXJlIHRoZW0gYnkgcmVmZXJlbmNlISAgSWYgQ1VEQSBpcyBlbmFibGVkLFxuICAvLyB0aGlzIG1hY3JvIG1heSBoYXZlIGEgc3BlY2lhbCBkZWZpbml0aW9uIHRoYXQgbWFrZXMgdGhlIGxhbWJkYVxuICAvLyB3b3JrIGNvcnJlY3RseSB3aXRoIENVREEuICBDb21wYXJlIHRvIHRoZSBLT0tLT1NfSU5MSU5FX0ZVTkNUSU9OXG4gIC8vIG1hY3JvLCB3aGljaCBoYXMgYSBzcGVjaWFsIG1lYW5pbmcgaWYgQ1VEQSBpcyBlbmFibGVkLlxuICAvL1xuICAvLyBUaGUgZm9sbG93aW5nIHBhcmFsbGVsX2ZvciB3b3VsZCBsb29rIGxpa2UgdGhpcyBpZiB3ZSB3ZXJlIHVzaW5nXG4gIC8vIE9wZW5NUCBieSBpdHNlbGYsIGluc3RlYWQgb2YgS29ra29zOlxuICAvL1xuICAvLyAjcHJhZ21hIG9tcCBwYXJhbGxlbCBmb3JcbiAgLy8gZm9yIChpbnQgaSA9IDA7IGkgPCAxNTsgKytpKSB7XG4gIC8vICAgcHJpbnRmIChcIkhlbGxvIGZyb20gaSA9ICVpXFxuXCIsIGkpO1xuICAvLyB9XG4gIC8vXG4gIC8vIFlvdSBtYXkgbm90aWNlIHRoYXQgdGhlIHByaW50ZWQgbnVtYmVycyBkbyBub3QgcHJpbnQgb3V0IGluXG4gIC8vIG9yZGVyLiAgUGFyYWxsZWwgZm9yIGxvb3BzIG1heSBleGVjdXRlIGluIGFueSBvcmRlci5cbiAgLy8gV2UgYWxzbyBuZWVkIHRvIHByb3RlY3QgdGhlIHVzYWdlIG9mIGEgbGFtYmRhIGFnYWluc3QgY29tcGlsaW5nXG4gIC8vIHdpdGggYSBiYWNrZW5kIHdoaWNoIGRvZXNuJ3Qgc3VwcG9ydCBpdCAoaS5lLiBDdWRhIDYuNS83LjApLlxuI2lmIGRlZmluZWQoS09LS09TX0VOQUJMRV9DWFgxMV9ESVNQQVRDSF9MQU1CREEpXG4gIEtva2tvczo6cGFyYWxsZWxfZm9yKFxuICAgICAgMTUsIEtPS0tPU19MQU1CREEoY29uc3QgaW50IGkpIHtcbiAgLy8gRklYTUVfU1lDTCBuZWVkcyB3b3JrYXJvdW5kIGZvciBwcmludGZcbiNpZm5kZWYgX19TWUNMX0RFVklDRV9PTkxZX19cbiAgICAgICAgLy8gcHJpbnRmIHdvcmtzIGluIGEgQ1VEQSBwYXJhbGxlbCBrZXJuZWw7IHN0ZDo6b3N0cmVhbSBkb2VzIG5vdC5cbiAgICAgICAgcHJpbnRmKFwiSGVsbG8gZnJvbSBpID0gJWlcXG5cIiwgaSk7XG4jZWxzZVxuXHQodm9pZClpO1xuI2VuZGlmXG4gICAgICB9KTtcbiNlbmRpZlxuICAvLyBZb3UgbXVzdCBjYWxsIGZpbmFsaXplKCkgYWZ0ZXIgeW91IGFyZSBkb25lIHVzaW5nIEtva2tvcy5cbiAgS29ra29zOjpmaW5hbGl6ZSgpO1xufVxuIiwgImNvbXBpbGVycyI6IFt7ImlkIjogImcxMzIiLCAib3B0aW9ucyI6ICItTzMiLCAibGlicyI6IFt7Im5hbWUiOiAia29ra29zIiwgInZlciI6ICI0MTAwIn1dfV19XX0=