I am specifically interested in Literate Programming in which the documentation and source code are in one file. Org-Mode has support for Babel's ability to embed source code blocks. One shortcoming is that syntactical highlighting doesn't work, and you can't take advantage of the full Language-mode features when the block is in Org-Mode.
Babel supports 'tangling' source code, which copies the source code into a named file, such as test.py. I am looking for a solution which will let me develop the source code in a fully featured Language-Mode, while being able to document that code, explaining the 'Why', in org mode.
Within the <body>
of a source code block
#+NAME: <name>
#+BEGIN_SRC <language> <switches> <header arguments>
<body>
#+END_SRC
C-c '
will open a buffer in the appropriate major mode for <language>
. The Babel documentation is here.