为了使读者可以清楚地将结果与生成结果的代码相匹配，最有用的方法是为论文编写代码？

我正在写一篇可复制的论文，该论文具有由Python脚本生成的计算结果（类似的MATLAB脚本生成几乎相同的结果）。我认为，如果读者可以将论文中的计算结果与代码中的计算结果相匹配，则读者会更容易理解本文。该工作提出了一种抽象的形式主义，并且本文中的示例应使这种形式主义对读者（其中很多是工程师）更加具体。该代码可能是有关如何执行计算的最详细记录，并且将其弄清楚可以在审核过程中为我们提供帮助。

是否有人对如何使代码与计算结果（数字，方程式）之间的对应关系更清晰有任何建议？

例如，我当时在想实现本文中各个步骤的代码行，我可以引用方程式编号（如果我可以在代码和LaTeX之间进行交叉引用，那真是太神奇了，但是手动标记它们就可以了） ，我可以编写与各种示例和图相对应的函数，例如

def example_1():
    # Insert code corresponding to first example
    pass

def figure_1():
    # Insert code that generates Figure 1
    pass

如果代码很大，而我并不想解释工程中使用的一堆不同的数学方法实际上是如何相同的，那么我可能不会很费心地使代码清晰明了，但是鉴于代码的抽象性质本文和少量的代码基础，似乎在此练习中可能有价值。

1. 您可以考虑将整个论文写在Noweb中。设置起来有点繁琐，但这是混合代码和LaTeX格式的文本，方程式和图形的一种非常有效的方法。对于长程序，它倾向于使您的代码变成一本书而不是一篇文章，但是对于短程序，它可能效果很好。

2. 如果您不想走那么远，那么使用LaTeX格式化代码清单的注释部分仍然应该相当简单。该listings软件包可以帮助您实现这一目标。这是一个简短的示例：

\ documentclass {article}
\ usepackage {amsmath}
\ usepackage {列表}
\ begin {document}
\ begin {equation}
  \ label {eq：one}
  轴= b
\ end {equation}
\ begin {lstlisting} [escapechar = \％]
  ＃引用方程式％〜\ eqref {eq：one}％进行注释
  def f（a）：
    返回a + 1
\ end {lstlisting}
\ end {document}

通过一些其他操作，您应该应该能够将引用的方程式编号显示在用于列出方程式的等宽字体中。

Bill提到的noweb方法已经有了相当大的发展，这既是其本来就是用“ 识字编程”这一术语来记录代码（而不是科学出版物）的原始精神，现在却出现了许多风格（我想noweb最初是cweb的概括），哪些doxygen版本以及各种特定于语言的版本可以生成TeX，HTML和其他格式的文档。

更重要的是，noweb已经在R社区中发展了一段时间（最初是S社区，因此名称）为“ Sweave”，目的是提供“可重现的研究”论文，其中的代码实际上在乳胶文件将被编译（也可以选择显示）。大量的学术论文都用Sweave编写（我相信包括所有R期刊；但也请参阅《生物统计学》杂志及其对可复制论文的政策）。

尽管Sweave仍然是任何基本R安装的一部分，但现在已被knitr取代，后者现在已与语言无关，从而使其成为python代码的可能选择。Knitr支持用LaTeX或markdown编写，支持语法高亮显示，缓存，源胶乳代码的外部化以及此类工作的许多其他理想功能。

Python拥有自己的类似解决方案，即ipython notebooks，可以呈现为HTML，也许是LaTeX，但我对此知之甚少。

绝对值得一看的另一个项目是dexyit，它是另一个与语言无关的程序，可与LaTeX和HTML很好地配合使用。尽管在记录代码方面比在撰写科学论文方面拥有更多示例，但在LaTeX中工作应该很简单。

双方knitr并dexyit会做什么，你在LaTeX的介绍，其中包括指向外部python脚本，并在码读取。尽管我对这种方法不太熟悉，但在DocBook和XML中可以完成类似的事情。

铸造的LaTeX包提供了非常广泛的语法突出显示（基于Pygments），并允许双向交叉引用。您可以从代码部分（铸造的部分）中转至LaTeX，并且可以在主体文本中引用代码行。最重要的是，它提供了清单环境，因此您可以生成“清单列表”（如表列表）并允许引用整个清单。请参阅下面的LaTeX MWE及其与LuaLaTeX的输出（不要判断代码:-））。

另一个选择是使用来自同一作者/维护者的PythonTeX，它允许在编译LaTeX源代码的同时运行计算，因此纸张和代码结果总是一起生成的，因此始终是连贯的。在这里查看PythonTeX画廊。

\documentclass[a4paper,notitlepage,11pt]{article}

\usepackage{amsmath}
\usepackage{cases}
\usepackage{minted}

\begin{document}

The mathematical definition of the Fibonacci
series is given in~Equations~(\ref{eq:fibdef:init1}--\ref{eq:fibdef:rule})
It can be implemented using either a recursive or iterative algorithm
in Python.

\begin{numcases}{f(n)=}
  \label{eq:fibdef}
    0               & n = 0 \label{eq:fibdef:init1}\\
    1               & n = 1 \label{eq:fibdef:init2}\\
    f(n-1) + f(n-2) & \text{otherwise} \label{eq:fibdef:rule}
\end{numcases}

The algorithms below are an implementation of both variants.
Listing~\ref{alg:fib_recursive} shows the recursive variant (see
line~\ref{alg:fibo_rec:line_rec} in listing~\ref{alg:fib_recursive}) while
listing~\ref{alg:fib_iterative} shows the iterative variant. Both can be
optimized, of course.

\begin{listing}[ht]
  \begin{minted}[linenos, escapeinside=||]{python}
def fibo_rec(N):
    if N == 0:
        result = 1 |[Comment: See case (\ref{eq:fibdef:init1})]|
    elif N == 1:
        result = 1 |[Comment: See case (\ref{eq:fibdef:init2})]|
    else:
        result = fibo_rec(N-1) + fibo_rec(N-2) |\label{alg:fibo_rec:line_rec}[Comment: See case (\ref{eq:fibdef:rule})]|

    return result
  \end{minted}
\caption{Fibonacci recursive}
\label{alg:fib_recursive}
\end{listing}

\begin{listing}[ht]
  \begin{minted}[linenos, escapeinside=||]{python}
def fibo_iter(N):
    if N == 0:
        fib_N = 1
    elif N == 1:
        fib_N = 1
    else:
        fib_Nmin2 = 1
        fib_Nmin1 = 1
        for i in range(2,N+1):
            fib_N = fib_Nmin2 + fib_Nmin1
            fib_Nmin2 = fib_Nmin1
            fib_Nmin1 = fib_N
    return fib_N
  \end{minted}
\caption{Fibonacci iterative}
\label{alg:fib_iterative}
\end{listing}

\end{document}

使用org-mode的文字编程功能。

大多数组织模式用户倾向于只专注于内置的项目/时间管理功能或从易于维护的文本文件将文档导出为多种流行文件格式（例如PDF）的功能。

但是，组织模式的最大特点是能够创建30多种语言的识字程序，而开源社区每月都会增加更多的语言。

以下是使用Ruby和Python的简单代码示例：

 #+NAME: trivial-code-ex1
 #+BEGIN_SRC ruby 
   "hello world!"
 #+END_SRC

 #+RESULTS: trivial-code-ex1
 : hello world!


 #+NAME: func-of-x-and-y
 #+BEGIN_SRC python :var x=1 :var y=2 :session
   x + y
 #+END_SRC

 #+RESULTS: func-of-x-and-y
 : 3

优点

• 支持30多种编程语言，包括R，Python，Ruby，Perl，C，C ++，Java，Clojure，Javascript，Common Lisp，Shell，SQL等。

• 的能力：

  • 捕获 SRC块结果作为输出和/或值。
  • 将 SRC块结果格式化为代码，列表，表，乳胶，html
  • 将外部和内部数据都用于SRC块的变量。
  • 将命名SRC块的输出SRC用作变量。
  • noweb在SRC块内使用语法。

    专家提示：您可以使用noweb语法来：

    • 从一个命名的SRC块中插入代码，例如func-of-x-and-y，在另一个SRC块中。

      #+BEGIN_SRC python :session :noweb yes 
        x=2
        y=3
        "f(x,y) is\n\n <<func-of-x-and-y>> \n\nso f({0},{1}) equals\n\n {2}".format(x,y,<<func-of-x-and-y>>)
      #+END_SRC
      
      #+RESULTS:
      : f(x,y) is
      : 
      :  x + y 
      : 
      : so f(2,3) equals
      : 
      :  5

    • 插入命名SRC块的结果，例如func-of-x-and-y在另一个SRC块内

      #+BEGIN_SRC python :session :noweb yes 
        "f(x,y) is\n\n <<func-of-x-and-y>> \n\nso f(3,4) equals\n\n <<func-of-x-and-y(x=3,y=4)>>"
      #+END_SRC
      
      #+RESULTS:
      : f(x,y) is
      : 
      :  x + y 
      : 
      : so f(3,4) equals
      : 
      :  7

    • 将命名SRC块放置在组织模式文件中的任何位置以提高可读性，并使用:tangle标头或将代码导出到外部源文件中。

• 开源项目-既像啤酒一样免费，也像自由一样免费。

• 文本文件格式可与git等版本控制软件配合使用。
• 其他功能不胜枚举，因为这个答案越来越长。

缺点

• 需要安装gnu emacs并将其配置为使用org-mode。

  注意：阅读gnu emacs后，大多数人都停止阅读此答案。对于剩下的勇敢者，您可以使用您喜欢的文本编辑器，只需调用emacs从命令行处理组织模式文件。

• 需要安装和配置所需的所有编程软件。

• 如果要制作PDF，则需要安装和配置LaTeX实用程序。
• 组织模式没有很好地知道的ipython notebooks或者Sweave所以你可能不会看到的，即使在2008年加入文学编程功能的许多工作职位。
• 学习组织模式标记语法
• 如果想从使用组织模式的其他出色工具中获得最大收益，则有可能学习如何使用gnu emacs或spacemacs。

全面披露：我是Atom编辑器的org-mode 软件包的主要维护者。

---

使用以下命令验证了此答案中的代码：
emacs版本：GNU Emacs 25.2.1
组织模式版本：9.1.2