Quale sarebbe il modo più utile per scrivere il codice per un documento in modo che i lettori possano abbinare chiaramente i risultati al codice che li genera?

Sto scrivendo un documento riproducibile e il documento ha risultati computazionali che sono generati da uno script Python (uno script MATLAB simile genera risultati quasi identici). Ritengo che il documento sarebbe più facile da capire per i lettori se potessero abbinare i calcoli nel documento con i calcoli nel codice. Il lavoro propone un formalismo astratto e gli esempi nel documento dovrebbero rendere questo formalismo più concreto per i lettori (molti dei quali saranno ingegneri); il codice sarà probabilmente il record più dettagliato su come eseguire i calcoli e chiarirlo potrebbe aiutarci durante il processo di revisione.

Qualcuno ha qualche suggerimento su come rendere più chiara la corrispondenza tra codice e risultati computazionali (figure, equazioni)?

Ad esempio, pensavo che quando si trattava di righe di codice che implementavano vari passaggi nel documento, potevo citare i numeri delle equazioni (sarebbe sorprendente se potessi incrociare il riferimento tra il codice e LaTeX, ma etichettarli a mano va bene) e potrei scrivere funzioni corrispondenti ai vari esempi e figure, come

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

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

Se il codice fosse grande e non stavo cercando di spiegare come un mucchio di diversi metodi matematici usati in ingegneria fossero effettivamente gli stessi, probabilmente non mi preoccuperei tanto di chiarire il codice, ma data la natura astratta del carta e la piccola base di codice, sembra che ci potrebbe essere valore in questo esercizio.

1. Potresti considerare di scrivere l'intero documento in Noweb . È un po 'noioso da configurare, ma è un modo molto potente per mescolare codice, testo, equazioni e cifre in formato LaTeX. Per programmi lunghi, tende a trasformare il codice in più di un libro che in un articolo, ma per programmi brevi, potrebbe funzionare abbastanza bene.

2. Se non vuoi andare così lontano, dovrebbe essere ragionevolmente semplice formattare le sezioni dei commenti delle tue liste di codici usando LaTeX. Il listingspacchetto può aiutarti a risolverlo. Ecco un breve esempio:

\ Documentclass {article}
\ Usepackage {amsmath}
\ usepackage {} annunci
\ Begin {document}
\ Begin {equation}
  \ Label {eq: uno}
  Ax = b
\ End {equation}
\ Begin {lstlisting} [EscapeChar = \%]
  # Commento con riferimento all'equazione% ~ \ eqref {eq: one}%
  def f (a):
    ritorna a + 1
\ End {} lstlisting
\ End {document}

Con alcune manipolazioni aggiuntive, dovresti essere in grado di far apparire i tuoi numeri di equazione referenziati nel carattere monospaziale che usa per elencare l'equazione.

L'approccio noweb menzionato da Bill si è evoluto un po ', sia nel suo spirito originale di documentare il codice (piuttosto che nella pubblicazione scientifica) sotto il termine programmazione alfabetica e ora arriva in molti modi (immagino che noweb fosse inizialmente una generalizzazione di cweb), di quale doxygene varie versioni specifiche della lingua possono generare documentazione in TeX, HTML e altri formati.

Più precisamente, noweb è stato sviluppato per qualche tempo nella Rcomunità (bene in origine la Scomunità, da cui il nome) sotto il titolo "Sweave" con l'obiettivo di fornire un documento di "ricerca riproducibile", in cui il codice viene effettivamente eseguito quando il file in lattice viene compilato (e facoltativamente visualizzato anche). Parecchi articoli accademici sono scritti in Sweave (incluso, credo, tutto il giornale R; ma vedi anche il giornale della biostatistica e la sua politica sui documenti riproducibili).

Mentre Sweave fa ancora parte di qualsiasi installazione di base R, viene sostituito da knitr, che ora è indipendente dal linguaggio , rendendolo una scelta possibile per il tuo codice Python. Knitr supporta la scrittura in LaTeX o markdown, supportando l'evidenziazione della sintassi, la memorizzazione nella cache, l'esternalizzazione del codice dal lattice di origine e molte altre caratteristiche desiderabili per questo tipo di lavoro.

Python ha le sue soluzioni simili, i notebook ipython , che possono eseguire il rendering in HTML, forse LaTeX, ma ne so di meno.

Un altro progetto che merita sicuramente una visita è dexyit , un altro programma indipendente dalla lingua che funziona molto bene con LaTeX e HTML. Mentre ha più esempi nella documentazione del codice che nella stesura di articoli scientifici, lavorare in LaTeX dovrebbe essere semplice.

Entrambi knitre dexyitfaranno esattamente ciò che descrivi in ​​LaTeX, incluso il puntamento a script Python esterni e la lettura nel codice. Cose simili possono essere realizzate in DocBook e XML, anche se ho meno familiarità con questo approccio.

Il pacchetto LaTeX coniato fornisce un'evidenziazione della sintassi molto estesa (basata su Pygments) e consente riferimenti incrociati in entrambe le direzioni. Puoi uscire da LaTeX dalla parte del codice (la parte coniata) e puoi fare riferimento nel tuo testo principale a righe di codice. Inoltre, fornisce un ambiente di elenchi in modo da poter generare un "elenco di elenchi" (come un elenco di tabelle) e consente di fare riferimento a interi elenchi. Vedi LaTeX MWE e il suo output con LuaLaTeX di seguito (non giudicare il codice :-)).

Un'altra opzione sarebbe quella di utilizzare PythonTeX dallo stesso autore / maintainer che consente di eseguire i calcoli durante la compilazione dell'origine LaTeX, quindi i risultati di carta e codice sono sempre generati insieme e quindi sono sempre coerenti. Guarda la galleria PythonTeX qui.

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

Utilizzare la funzionalità di programmazione alfabetica della modalità org .

La maggior parte degli utenti in modalità org tendono a concentrarsi esclusivamente sulla funzionalità di gestione del progetto / tempo integrata o sulla capacità di esportare documenti in più formati di file popolari, ad esempio PDF , da testo facile da mantenere file di .

Tuttavia, la migliore caratteristica della modalità org è la possibilità di creare programmi alfabetici in oltre 30 lingue con più lingue aggiunte ogni mese dalla comunità open source.

Di seguito sono riportati esempi di codice banali usando Ruby e 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

Professionisti

• Supporto per oltre 30 linguaggi di programmazione , tra cui R, Python, Ruby, Perl, C, C ++, Java, Clojure, Javascript, Common Lisp, Shell, SQL, ...

• L'abilità di:

  • Catturare SRC risultati del blocco come output e / o valore.
  • Formato SRC risultati del blocco come codice, elenchi, tabella, latex, html
  • Utilizza sia dati esterni che interni per variabili di SRC blocchi.
  • Utilizzare l'output di SRCblocchi denominati in SRCblocchi come variabili.
  • Usa la nowebsintassi all'interno dei SRCblocchi.

    Suggerimento professionale: è possibile utilizzare la nowebsintassi per:

    • inserire il codice da un SRCblocco denominato , ad esempio func-of-x-and-y, all'interno di un altro SRCblocco.

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

    • inserire i risultati di un SRCblocco denominato , ad esempio func-of-x-and-yall'interno di un altro SRCblocco

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

    • Posiziona i SRCblocchi con nome ovunque in un file in modalità org per la leggibilità e utilizza l' :tangleintestazione o il codice di esportazione in file di origine esterni.

• Progetto open source - sia gratis che nella birra e liberi come nella libertà.

• Il formato di file di testo funziona perfettamente con software di controllo versione come git.
• Ooodles di altre caratteristiche che non affronterò perché questa risposta sta diventando lunga.

Contro

• È necessario che gnu emacs sia installato e configurato per utilizzare la modalità org.

  Nota: la maggior parte di voi ha smesso di leggere questa risposta dopo aver letto gnu emacs. Per le anime coraggiose rimaste, puoi usare il tuo editor di testo preferito e chiamare emacs per elaborare i tuoi file in modalità org dalla riga di comando.

• È necessario installare e configurare tutto il software di programmazione necessario.

• È necessario installare e configurare i programmi di utilità LaTeX se si desidera creare PDF.
• org-mode non è così noto come ipython notebookso Sweavecosì probabilmente non vedrai tante offerte di lavoro anche se nel 2008 è stata aggiunta la funzionalità di programmazione letterata.
• Apprendimento della sintassi del markup in modalità org
• Potenzialmente imparare come usare gnu emacs o spacemacs se vuoi ottenere il massimo dagli altri fantastici strumenti che funzionano con la modalità org.

Divulgazione completa: sono il principale manutentore del pacchetto in modalità org per l'editor Atom.

---

Il codice in questa risposta è stato validato usando:
emacs versione: GNU Emacs 25.2.1
versione org-mode: 9.1.2