Include sections of org document in tangled files

Include sections of org document in tangled files

[David Dynerman]

Dear list,

Is it possible to include sections of an org document while tangling.

I have in mind something like the following:

* Some section
<<doc>>
This is an introduction. We're going to write some code that implements (a finite version of) the formula

\[
f(x) = 1 + x + \frac{x^2}{2} + \frac{x^3}{6} + \ldots + \frac{x^n}{n!} + \ldots
\]

Here's some background about the exponential function.

#+BEGIN_SRC python :tangle myfunction.py
from math import factorial

def f(x,n):
    """<<doc>>"""

    y = 0
    for i in range(n+1):
        y = y + x**i/factorial(i)

    return y
#+END_SRC

The idea would be that when I export this to HTML, I get a nice literate
programming math jax'd section introduction that explains what the
function is doing. Then, when I tangle to generate the python file, the
org section introduction would be included as the python docstring of
the function.

This would be really useful, because currently I find myself repeating
information when I use org for literate programming. First, I explain
what a python function is doing in the org file, but then I also want to
include a docstring in the tangled output that basically contains the
same information as the org file.

Thank you,
David

Re: Include sections of org document in tangled files

[Charles C. Berry]

On Fri, 2 Dec 2016, David Dynerman wrote:

> Dear list,
>
> Is it possible to include sections of an org document while tangling.
>
> I have in mind something like the following:
>
> * Some section

[David's version deleted]

#+NAME: doc
#+BEGIN_SRC org :exports results :results replace
   This is an introduction. We're going to write some code that
   implements (a finite version of) the formula

   \[
   f(x) = 1 + x + \frac{x^2}{2} + \frac{x^3}{6} + \ldots +
   \frac{x^n}{n!} + \ldots
   \]

   Here's some background about the exponential function.

#+END_SRC

#+header: :noweb (unless org-export-current-backend "yes")
#+BEGIN_SRC python :tangle myfunction.py
   from math import factorial

   def f(x,n):
       """
       <<doc>>
       """

       y = 0
       for i in range(n+1):
           y = y + x**i/factorial(i)

       return y
#+END_SRC


> The idea would be that when I export this to HTML, I get a nice literate
> programming math jax'd section introduction that explains what the
> function is doing.

Right. The above does that.

You need `org' as a babel language. Eval'ing `(require 'ob-org)' is good 
enough for just trying to export this, but customizing 
`org-babel-load-languages' to include `org' is better if you use this 
regularly.


> Then, when I tangle to generate the python file, the
> org section introduction would be included as the python docstring of
> the function.
>

And it does that.

---

There is an issue you might want to address if you use this approach. 
First, the first triple quotes must not be on the same line as the 
included src block reference. That is because """<src-blk-ref>>""" will 
prepend the quotes to every line in `src-blk-ref'.

If you do not want the newlines between the quotes and the docstring, I 
think there is a post-tangle hook you can use to clean the tangled version 
by removing those newlines.

Also, you can use an export filter to remove the quotes and the noweb 
reference for a cleaner looking exported doc.

Note that you need to use a unique name for each src-block.

HTH,

Chuck

Re: Include sections of org document in tangled files

[David Dynerman]

Dear Chuck,

Your suggestion worked fantastically - I got it working and am very excited.

Now, the next step is figuring out how to handle typesetting math in single way between org and python docstrings. Math in Python docstrings is usually done by RestructuredText markdown, e.g.:

:math:`f(x) = x^2`

while the org code should just be, for example,

\[
f(x) = x^2
\]

So the goal would be have noweb not only include a documentation block in the python code, but also call a translation function that identifies LaTeX fragments in the org source and converts them to ReST markdown.

That's a separate project though, for now your suggestion is really cool!

Thanks a lot,
David

"Charles C. Berry" <ccberry@ucsd.edu> writes:

> #+NAME: doc
> #+BEGIN_SRC org :exports results :results replace
>    This is an introduction. We're going to write some code that
>    implements (a finite version of) the formula
>
>    \[
>    f(x) = 1 + x + \frac{x^2}{2} + \frac{x^3}{6} + \ldots +
>    \frac{x^n}{n!} + \ldots
>    \]
>
>    Here's some background about the exponential function.
>
> #+END_SRC
>
> #+header: :noweb (unless org-export-current-backend "yes")
> #+BEGIN_SRC python :tangle myfunction.py
>    from math import factorial
>
>    def f(x,n):
>        """
>        <<doc>>
>        """
>
>        y = 0
>        for i in range(n+1):
>            y = y + x**i/factorial(i)
>
>        return y
> #+END_SRC
>
>
>> The idea would be that when I export this to HTML, I get a nice literate
>> programming math jax'd section introduction that explains what the
>> function is doing.
>
> Right. The above does that.
>
> You need `org' as a babel language. Eval'ing `(require 'ob-org)' is good 
> enough for just trying to export this, but customizing 
> `org-babel-load-languages' to include `org' is better if you use this 
> regularly.
>
>
>> Then, when I tangle to generate the python file, the
>> org section introduction would be included as the python docstring of
>> the function.
>>
>
> And it does that.
>
> ---
>
> There is an issue you might want to address if you use this approach. 
> First, the first triple quotes must not be on the same line as the 
> included src block reference. That is because """<src-blk-ref>>""" will 
> prepend the quotes to every line in `src-blk-ref'.
>
> If you do not want the newlines between the quotes and the docstring, I 
> think there is a post-tangle hook you can use to clean the tangled version 
> by removing those newlines.
>
> Also, you can use an export filter to remove the quotes and the noweb 
> reference for a cleaner looking exported doc.
>
> Note that you need to use a unique name for each src-block.
>
> HTH,
>

Re: Include sections of org document in tangled files

[Charles C. Berry]

On Wed, 7 Dec 2016, David Dynerman wrote:

> Dear Chuck,
>
> Your suggestion worked fantastically - I got it working and am very excited.
>
> Now, the next step is figuring out how to handle typesetting math in single way between org and python docstrings. Math in Python docstrings is usually done by RestructuredText markdown, e.g.:
>
> :math:`f(x) = x^2`
>
> while the org code should just be, for example,
>
> \[
> f(x) = x^2
> \]
>

> So the goal would be have noweb not only include a documentation block 
> in the python code, but also call a translation function that identifies 
> LaTeX fragments in the org source and converts them to ReST markdown.
>

This is do-able.

First, look at

 	(info "(org) Noweb reference syntax")

and note that the noweb reference

 	<<my-src-block(x="value_for_x")>>

will call `my-src-block' with the `x' var set to "value_for_x" and insert 
the output into the current src block.

Second, https://github.com/masayuko/ox-rst has a reStructuredText backend. 
So, you can install ox-rst.el, then write an emacs-lisp src block:


#+NAME: export-body
#+BEGIN_SRC emacs-lisp :var src-block-name="my-code" :results raw
   (save-excursion
     (org-babel-goto-named-src-block
      src-block-name)
     (org-export-string-as
      (org-babel-expand-src-block)
      'rst t))
#+END_SRC

and then a src-block like this

#+BEGIN_SRC emacs-lisp :noweb yes :tangle yes
<<export-body("my-code")>>
#+END_SRC

will insert the rst formatted text from the `my-code' src block when the 
latter src block is tangled.

p.s. Untested with 'rst.

HTH,

Chuck