Điều gì sẽ là cách hữu ích nhất để viết mã cho một bài báo để người đọc có thể khớp rõ ràng kết quả với mã tạo ra chúng?

Tôi đang viết một bài báo có thể tái tạo và bài báo có kết quả tính toán được tạo bởi tập lệnh Python (tập lệnh MATLAB tương tự tạo ra kết quả gần như giống hệt nhau). Tôi cảm thấy rằng bài báo sẽ dễ hiểu hơn cho người đọc nếu họ có thể kết hợp các phép tính trong bài viết với các phép tính trong mã. Tác phẩm đề xuất một chủ nghĩa hình thức trừu tượng, và các ví dụ trong bài báo được cho là làm cho chủ nghĩa hình thức này trở nên cụ thể hơn cho độc giả (nhiều người trong số họ sẽ là kỹ sư); mã có thể sẽ là bản ghi chi tiết nhất về cách thực hiện các phép tính và làm cho nó rõ ràng có thể giúp chúng tôi trong quá trình xem xét.

Có ai có bất kỳ đề xuất nào về cách làm cho sự tương ứng giữa mã và kết quả tính toán (số liệu, phương trình) rõ ràng hơn không?

Ví dụ, tôi đã nghĩ rằng khi nói đến các dòng mã thực hiện các bước khác nhau trong bài báo, tôi có thể trích dẫn các số phương trình (thật tuyệt vời nếu tôi có thể tham chiếu chéo giữa mã và LaTeX, nhưng dán nhãn bằng tay là tốt) và tôi có thể viết các hàm tương ứng với các ví dụ và số liệu khác nhau, chẳng hạn như

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

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

Nếu mã lớn và tôi không cố giải thích làm thế nào một loạt các phương pháp toán học khác nhau được sử dụng trong kỹ thuật thực sự giống nhau, tôi có lẽ sẽ không bận tâm nhiều đến việc làm cho mã rõ ràng, nhưng mang bản chất trừu tượng của giấy và cơ sở mã nhỏ, dường như có thể có giá trị trong bài tập này.

1. Bạn có thể xem xét viết toàn bộ bài viết trong Noweb . Việc cài đặt hơi tẻ nhạt, nhưng đó là một cách rất mạnh để trộn mã và văn bản, phương trình và số liệu có định dạng LaTeX. Đối với các chương trình dài, nó có xu hướng biến mã của bạn thành nhiều sách hơn là một bài viết, nhưng đối với các chương trình ngắn, nó có thể hoạt động khá tốt.

2. Nếu bạn không muốn đi xa đến thế, bạn vẫn nên đơn giản hợp lý để định dạng các phần nhận xét của danh sách mã của mình bằng LaTeX. Các listingsgói có thể giúp bạn kéo ra. Đây là một ví dụ ngắn:

\ document class {article}
\ usepackage {amsmath}
\ usepackage {danh sách}
\ bắt đầu {tài liệu}
\ bắt đầu {phương trình}
  \ nhãn {eq: một}
  Rìu = b
\ end {phương trình}
\ bắt đầu {lstlisting} [escapechar = \%]
  # Nhận xét có tham chiếu đến phương trình% ~ \ eqref {eq: one}%
  def f (a):
    trả lại + 1
\ end {lstlisting}
\ end {tài liệu}

Với một số thao tác bổ sung, bạn phải có thể làm cho các số phương trình được tham chiếu của mình xuất hiện trong phông chữ đơn cách mà nó sử dụng để liệt kê phương trình.

Cách tiếp cận noweb được Bill đề cập đã phát triển khá nhiều, cả về tinh thần ban đầu của mã tài liệu (chứ không phải là xuất bản khoa học) theo thuật ngữ lập trình chữ và bây giờ có nhiều hương vị (tôi đoán ban đầu là một khái quát của cweb), của đó doxygenvà các phiên bản ngôn ngữ cụ thể khác nhau có thể tạo ra tài liệu trong TeX, HTML, và các định dạng khác.

Theo quan điểm của bạn, noweb đã được phát triển một thời gian trong Rcộng đồng (ban đầu là Scộng đồng, do đó có tên) với tiêu đề "Sweave" với mục tiêu cung cấp một bài báo "nghiên cứu có thể tái tạo", nơi mã thực sự được chạy khi tập tin latex được biên dịch (và cũng được hiển thị tùy chọn). Khá nhiều bài báo học thuật được viết bằng Sweave (bao gồm, tôi tin rằng, tất cả các tạp chí R; nhưng cũng xem tạp chí về thống kê sinh học và chính sách của nó trên các bài báo có thể tái tạo).

Mặc dù Sweave vẫn là một phần của bất kỳ cài đặt cơ sở R nào, nhưng nó đang được thay thế bằng đan , hiện là ngôn ngữ bất khả tri , làm cho nó trở thành một lựa chọn khả thi cho mã python của bạn. Đan hỗ trợ viết bằng LaTeX hoặc markdown, hỗ trợ tô sáng cú pháp, lưu vào bộ đệm, xuất ngoại mã từ latex nguồn và nhiều tính năng mong muốn khác cho loại công việc này.

Python có các giải pháp tương tự, máy tính xách tay ipython , có thể kết xuất thành HTML, có thể là LaTeX, nhưng tôi biết ít hơn về điều này.

Một dự án khác chắc chắn đáng xem là dexyit , một chương trình không biết ngôn ngữ khác hoạt động rất độc đáo với LaTeX và HTML. Mặc dù nó có nhiều ví dụ về mã tài liệu hơn là viết các bài báo khoa học, làm việc trong LaTeX, nó nên được tiến thẳng.

Cả hai knitrvà dexyitsẽ làm chính xác những gì bạn mô tả trong LaTeX, bao gồm chỉ vào tập lệnh python bên ngoài và đọc mã. Những điều tương tự có thể được thực hiện trong DocBook và XML, mặc dù tôi không quen với cách tiếp cận này.

Gói LaTeX được cung cấp làm nổi bật cú pháp rất rộng (dựa trên Pygments) và cho phép tham chiếu chéo theo cả hai hướng. Bạn có thể thoát đến LaTeX từ bên trong phần mã (phần được đúc) và bạn có thể tham chiếu trong văn bản chính của mình đến các dòng mã. Trên hết, nó cung cấp một môi trường danh sách để bạn có thể tạo một "danh sách danh sách" (như danh sách các bảng) và cho phép tham chiếu toàn bộ danh sách. Xem LaTeX MWE và đầu ra của nó với LuaLaTeX bên dưới (không phán xét mã :-)).

Một tùy chọn khác là sử dụng PythonTeX từ cùng một tác giả / người bảo trì, cho phép chạy các phép tính trong khi biên dịch nguồn LaTeX, do đó kết quả giấy và mã luôn được tạo cùng nhau và do đó luôn luôn kết hợp. Xem thư viện PythonTeX tại đây.

\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}

Sử dụng chức năng lập trình biết chữ của chế độ org .

Hầu hết người dùng chế độ org có xu hướng tập trung hoàn toàn vào chức năng quản lý dự án / thời gian tích hợp hoặc khả năng xuất tài liệu sang nhiều định dạng tệp phổ biến, ví dụ PDF , từ dễ duy trì tệp văn bản .

Tuy nhiên, tính năng tốt nhất của chế độ org là khả năng tạo các chương trình biết chữ bằng hơn 30 ngôn ngữ với nhiều ngôn ngữ được cộng đồng nguồn mở thêm vào mỗi tháng.

Dưới đây là các ví dụ mã tầm thường sử dụng Ruby và 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

Ưu

• Hỗ trợ hơn 30 ngôn ngữ lập trình , bao gồm R, Python, Ruby, Perl, C, C ++, Java, Clojure, Javascript, Lisp chung, Shell, SQL, ...

• Khả năng:

  • Nắm bắt SRC kết quả khối như đầu ra và / hoặc giá trị.
  • Định dạng SRC kết quả khối như mã, danh sách, bảng, latex, html
  • Sử dụng cả dữ liệu bên ngoài và bên trong cho các biến của SRCkhối.
  • Sử dụng đầu ra của SRCcác khối được đặt tên thành SRCcác khối làm biến.
  • Sử dụng nowebcú pháp bên trong SRCcác khối.

    Mẹo chuyên nghiệp: Bạn có thể sử dụng nowebcú pháp để:

    • chèn mã từ một SRCkhối được đặt tên , ví dụ func-of-x-and-y, bên trong một SRCkhối khác .

      #+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

    • chèn kết quả của một SRCkhối được đặt tên , ví dụ func-of-x-and-ybên trong một SRCkhối khác

      #+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

    • Đặt SRCcác khối được đặt tên ở bất cứ đâu trong tệp chế độ org để dễ đọc và sử dụng :tangletiêu đề hoặc xuất mã thành các tệp nguồn bên ngoài.

• Dự án nguồn mở - cả miễn phí như trong bia và miễn phí như trong tự do.

• Định dạng tệp văn bản hoạt động tuyệt vời với phần mềm kiểm soát phiên bản như git.
• Rất nhiều tính năng khác mà tôi sẽ không tìm hiểu vì câu trả lời này đang trở nên dài.

Nhược điểm

• Cần phải cài đặt và cấu hình gnu emacs để sử dụng chế độ org.

  Lưu ý: Hầu hết các bạn đã ngừng đọc câu trả lời này sau khi bạn đọc gnu emacs. Đối với những linh hồn dũng cảm còn sót lại, bạn có thể sử dụng trình soạn thảo văn bản yêu thích của mình và chỉ cần gọi emacs để xử lý các tệp chế độ tổ chức của bạn từ dòng lệnh.

• Cần cài đặt và cấu hình tất cả các phần mềm lập trình bạn cần.

• Cần cài đặt và định cấu hình các tiện ích LaTeX nếu bạn muốn tạo tệp PDF.
• Chế độ org không được biết nhiều như vậy ipython notebookshoặc Sweavecó lẽ bạn sẽ không thấy nhiều bài đăng công việc mặc dù chức năng Lập trình Văn học đã được thêm vào năm 2008.
• Học cú pháp đánh dấu chế độ org
• Có khả năng học cách sử dụng gnu emacs hoặc spacemacs nếu muốn tận dụng tối đa các công cụ tuyệt vời khác hoạt động với chế độ org.

Tiết lộ đầy đủ: Tôi là người duy trì chính của gói chế độ org cho trình soạn thảo Atom.

---

Mã trong câu trả lời này đã được xác thực bằng cách sử dụng:
phiên bản emacs: GNU Emacs 25.2.1
phiên bản org-mode: 9.1.2