読者が結果をそれらを生成するコードに明確に一致させることができるように、論文のコードを記述する最も役立つ方法は何でしょうか？

私は再現可能な論文を書いていますが、この論文には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 {記事}
\ usepackage {amsmath}
\ usepackage {listings}
\ begin {document}
\ begin {式}
  \ label {eq：one}
  Ax = b
\ end {equation}
\ begin {lstlisting} [escapechar = \％]
  ＃Equation％〜\ eqref {eq：one}％への参照を含むコメント
  def f（a）：
    a + 1を返す
\ end {lstlisting}
\ end {document}

いくつかの追加の操作を行うと、参照された方程式番号を取得して、方程式のリストに使用する等幅フォントで表示できるようになります。

Billが言及したnowebアプローチは、リテラティックプログラミングという用語の下で（科学出版ではなく）コードを文書化するという元の精神の両方でかなり進化しており、現在では多くのフレーバーがあります（nowebは当初cwebの一般化だったと思います）どのdoxygen言語固有のバージョンでも、TeX、HTML、およびその他の形式のドキュメントを生成できます。

nowebは、「再現性のある研究」論文を提供することを目的に、「Sweave」というタイトルでRコミュニティ（以前はSコミュニティ、つまり名前）でしばらく開発されてきました。ラテックスファイルがコンパイルされます（オプションで表示されます）。かなりの数の学術論文がSweaveで書かれています（Rジャーナルのすべてを含むと信じていますが、生物統計学のジャーナルと再現可能な論文に関するポリシーも参照してください）。

SweaveはまだベースRインストールの一部ですが、現在は言語に依存しないknitrに置き換えられており、Pythonコードの選択が可能になっています。Knitrは、LaTeXまたはマークダウンでの書き込みをサポートし、構文の強調表示、キャッシュ、ソースラテックスからのコードの外部化、およびこの種の作業に必要な他の多くの機能をサポートします。

Pythonには同様の独自のソリューションipython Notebookがあり、HTML、おそらくLaTeXにレンダリングできますが、これについてはあまり知りません。

間違いなく一見の価値がある別のプロジェクトはdexyitです。これは、LaTeXおよびHTMLで非常にうまく機能する、言語に依存しない別のプログラムです。科学論文を書くよりもコードを文書化する方が多くの例がありますが、LaTeXで作業するのは簡単です。

どちらknitrとdexyit外部の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のLiterate Programming Functionalityを使用します。

ほとんどの組織モードのユーザーは、組み込みのプロジェクト/時間管理機能、またはドキュメントを複数の一般的なファイル形式（PDFなど）に簡単に維持できるテキストファイルからエクスポートする機能にのみ焦点を当てる傾向があります。

ただし、org-modeの最も優れた機能は、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

長所

• R、Python、Ruby、Perl、C、C ++、Java、Clojure、Javascript、Common Lisp、Shell、SQLなど、30を超えるプログラミング言語のサポート

• 次の機能：

  • SRCブロックの結果を出力または値としてキャプチャします。
  • SRCブロック結果をコード、リスト、表、ラテックス、htmlとしてフォーマットする
  • SRCブロックの変数に外部データと内部データの両方を使用します。
  • 名前付きSRCブロックの出力をSRC変数としてブロックに使用します。
  • ブロックnoweb内で構文を使用しますSRC。

    プロのヒント：noweb構文を使用して次のことができます。

    • 別のブロック内SRCなど、名前付きブロックからコードを挿入します。func-of-x-and-ySRC

      #+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などのバージョン管理ソフトウェアでうまく機能します。
• この答えが長くなっているので、私は入りません他の機能のOoodles。

短所

• org-modeを使用するには、gnu emacsをインストールして構成する必要があります。

  注：ほとんどの人は、gnu emacsを読んだ後、この回答を読むのをやめました。残された勇敢な魂のために、あなたはあなたの好きなテキストエディタを使用して、コマンドラインから組織モードファイルを処理するためにemacsを呼び出すことができます。

• 必要なすべてのプログラミングソフトウェアをインストールして構成する必要があります。

• PDFを作成する場合は、LaTeXユーティリティをインストールして構成する必要があります。
• org-modeはあまり知られていipython notebooksないSweaveため、2008年にLiterate Programming機能が追加されたとしても、おそらくそれほど多くの求人情報は表示されません。
• 組織モードマークアップ構文の学習
• org-modeで動作する他のクールなツールを最大限に活用したい場合は、gnu emacsまたはspacemacsの使用方法を学習する可能性があります。

完全な開示：私は、Atomエディターのorg-mode パッケージの主要なメンテナーです。

---

この回答のコードは、
emacsバージョン：GNU Emacs 25.2.1
org-modeバージョン：9.1.2 を使用して検証されました