Jaki byłby najbardziej pomocny sposób pisania kodu dla artykułu, aby czytelnicy mogli wyraźnie dopasować wyniki do kodu, który je generuje?

Piszę powtarzalny artykuł, a artykuł ma wyniki obliczeń generowane przez skrypt Pythona (podobny skrypt MATLAB generuje prawie identyczne wyniki). Wydaje mi się, że artykuł byłby łatwiejszy do zrozumienia dla czytelników, gdyby mogli dopasować obliczenia w artykule do obliczeń w kodzie. Praca proponuje abstrakcyjny formalizm, a przykłady w artykule mają uczynić ten formalizm bardziej konkretnym dla czytelników (z których wielu będzie inżynierami); kod będzie prawdopodobnie najdokładniejszym zapisem sposobu wykonywania obliczeń, a jego wyjaśnienie może nam pomóc w procesie przeglądu.

Czy ktoś ma jakieś sugestie, jak wyjaśnić zgodność między kodem a wynikami obliczeniowymi (liczby, równania)?

Na przykład myślałem, że jeśli chodzi o wiersze kodu implementujące różne kroki w dokumencie, mogę zacytować liczby równań (byłoby niesamowite, gdybym mógł powiązać kod z LaTeX-em, ale ręczne etykietowanie ich jest w porządku) , i mógłbym pisać funkcje odpowiadające różnym przykładom i rysunkom, takie jak

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

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

Gdyby kod był duży, a ja nie próbowałem wyjaśnić, jak wiele różnych metod matematycznych stosowanych w inżynierii było w rzeczywistości takich samych, prawdopodobnie nie zawracałbym sobie głowy wyjaśnianiem kodu, ale biorąc pod uwagę abstrakcyjną naturę papier i mała podstawa kodu, wydaje się, że w tym ćwiczeniu może być wartość.

1. Możesz rozważyć napisanie całego artykułu w Nowymb . Konfiguracja jest nieco żmudna, ale jest to bardzo skuteczny sposób mieszania kodu z tekstem, równaniami i liczbami w formacie LaTeX-a. W przypadku długich programów kod zmienia się raczej w książkę niż artykuł, ale w przypadku krótkich programów może działać całkiem nieźle.

2. Jeśli nie chcesz posuwać się tak daleko, formatowanie sekcji komentarzy na listach kodów za pomocą LaTeX-a powinno być dość proste. listingsPakiet może pomóc ciągnąć ten off. Oto krótki przykład:

\ documentclass {article}
\ usepackage {amsmath}
\ usepackage {listings}
\ begin {document}
\ begin {równanie}
  \ label {eq: one}
  Ax = b
\ end {równanie}
\ begin {lstlisting} [escapechar = \%]
  # Komentarz z odniesieniem do równania% ~ \ eqref {eq: one}%
  def f (a):
    zwróć + 1
\ end {lstlisting}
\ end {dokument}

Przy niektórych dodatkowych manipulacjach powinieneś być w stanie uzyskać odniesienia do numerów równań, które pojawią się w czcionce o jednolitej przestrzeni używanej do wyliczenia równania.

Podejście nowegob, o którym wspomniał Bill, ewoluowało całkiem sporo, zarówno w oryginalnym duchu dokumentowania kodu (a nie publikacji naukowej) pod pojęciem programowania literackiego, a teraz ma wiele smaków (domyślam się, że noweb było początkowo uogólnieniem cweb), która doxygeni różne wersje językowe mogą generować dokumentację w TeX, HTML i innych formatach.

Co więcej, noweb zostało opracowane przez pewien czas w Rspołeczności (pierwotnie w Sspołeczności, stąd nazwa) pod tytułem „Sweave” w celu zapewnienia „powtarzalnego badania”, w którym kod jest uruchamiany, gdy plik lateksu jest kompilowany (i opcjonalnie również wyświetlany). W Sweave napisanych jest całkiem sporo artykułów naukowych (w tym, jak sądzę, cały dziennik R; ale patrz także dziennik biostatystyczny i jego polityka dotycząca powtarzalnych artykułów).

Chociaż Sweave jest nadal częścią każdej podstawowej instalacji R, jest on zastępowany przez knitr, który jest teraz niezależny od języka , co czyni go możliwym wyborem dla twojego kodu python. Knitr obsługuje pisanie w LaTeX-ie lub markdown, obsługuje podświetlanie składni, buforowanie, eksternalizację kodu z lateksu źródłowego i wiele innych pożądanych funkcji do tego rodzaju pracy.

Python ma własne rozwiązania, które są podobne, zeszyty ipython , które mogą renderować do HTML, może LaTeX, ale mniej o tym wiem.

Kolejnym projektem zdecydowanie wartym obejrzenia jest dexyit , inny program niezależny od języka, który działa bardzo dobrze z LaTeX i HTML. Chociaż ma więcej przykładów w dokumentowaniu kodu niż w pisaniu artykułów naukowych, praca w LaTeXie powinna być prosta.

Oba knitri dexyitzrobią dokładnie to, co opisujesz w LaTeX, włączając w to wskazywanie na zewnętrzny skrypt Pythona i wczytywanie kodu. Podobne rzeczy można osiągnąć w DocBook i XML, choć mniej znam tego podejścia.

Pakiet LaTeX wybite zapewnia bardzo szerokie podświetlanie składni (w oparciu o Pygments) i pozwala na powiązanie danych w obu kierunkach. Możesz uciec do LaTeXa z części kodowej (część wybita) i możesz odwoływać się w tekście głównym do wierszy kodu. Ponadto zapewnia środowisko listowania, dzięki czemu można wygenerować „listę list” (np. Listę tabel) i umożliwić odwoływanie się do całych list. Zobacz LaTeX MWE i jego dane wyjściowe z LuaLaTeX poniżej (nie oceniaj kodu :-)).

Inną opcją byłoby użycie PythonTeX od tego samego autora / opiekuna, który umożliwia uruchomienie obliczeń podczas kompilacji źródła LaTeX, dlatego wyniki papierowe i kodowe są zawsze generowane razem, a zatem są zawsze spójne. Zobacz galerię PythonTeX tutaj.

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

Skorzystaj z funkcji programowania umiejętności czytania i pisania w trybie org .

Większość użytkowników w trybie org koncentruje się wyłącznie na wbudowanej funkcji zarządzania projektami / czasem lub na możliwości eksportowania dokumentów do wielu popularnych formatów plików, np. PDF , z łatwych w utrzymaniu plików tekstowych .

Jednak najlepszą funkcją trybu org jest możliwość tworzenia programów czytania i pisania w ponad 30 językach, a co miesiąc dodawanych jest więcej języków przez społeczność open source.

Poniżej znajdują się trywialne przykłady kodu wykorzystujące Ruby i 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

Plusy

• Obsługa ponad 30 języków programowania , w tym R, Python, Ruby, Perl, C, C ++, Java, Clojure, JavaScript, Common Lisp, Shell, SQL, ...

• Zdolność do:

  • Przechwyć SRC wyniki bloku jako dane wyjściowe i / lub wartość.
  • Formatuj SRC wyniki bloków jako kod, listy, tabele, lateks, HTML
  • Użyj zmiennych zewnętrznych i wewnętrznych dla zmiennych SRCbloków.
  • Użyj danych wyjściowych nazwanych SRCbloków w SRCbloki jako zmienne.
  • Użyj nowebskładni w SRCblokach.

    Wskazówka: możesz użyć nowebskładni, aby:

    • wstaw kod z nazwanego SRCbloku, np. func-of-x-and-yw innym SRCbloku.

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

    • wstaw wyniki nazwanego SRCbloku, np. func-of-x-and-yw innym SRCbloku

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

    • Umieść nazwane SRCbloki w dowolnym miejscu w pliku trybu org dla czytelności i użyj :tanglenagłówka lub kodu eksportu do zewnętrznych plików źródłowych.

• Projekt open source - zarówno darmowy jak w piwie, jak i wolny jak wolność.

• Format pliku tekstowego działa świetnie z oprogramowaniem do kontroli wersji, takim jak git.
• Ooodles innych funkcji, w które nie wchodzę, ponieważ ta odpowiedź jest długa.

Cons

• Musisz mieć zainstalowany gnu emacs i skonfigurowany do korzystania z trybu org.

  Uwaga: Większość z was przestała czytać tę odpowiedź po przeczytaniu GNU emacs. W przypadku odważnych dusz, które pozostały, możesz użyć swojego ulubionego edytora tekstu i po prostu wywołać emacsa, aby przetworzyć pliki trybu org z wiersza poleceń.

• Musisz zainstalować i skonfigurować całe potrzebne oprogramowanie do programowania.

• Musisz zainstalować i skonfigurować narzędzia LaTeX, jeśli chcesz tworzyć pliki PDF.
• org-mode nie jest tak dobrze znane jak ipython notebooksi Sweavetak prawdopodobnie nie będzie widać, jak wiele ofert pracy, chociaż funkcjonalność Literate Programowanie został dodany w 2008 roku.
• Nauka składni znaczników w trybie org
• Potencjalnie ucz się, jak używać GNU Emacs lub SpaceMacs, jeśli chcesz jak najlepiej wykorzystać inne fajne narzędzia, które działają w trybie org.

Pełne ujawnienie: Jestem głównym opiekunem pakietu trybu org dla edytora Atom.

---

Kod w tej odpowiedzi został sprawdzony przy użyciu:
emacs version: GNU Emacs 25.2.1
org-mode version: 9.1.2