Zautomatyzowany sposób na przejście z formatowania doccriptowego epokeja na formatowanie z docinkiem?

Question

Mam projekt, który udokumentowałem za pomocą epydoc. Teraz próbuję przejść do sfinksa. Sformatowałem wszystkie moje docstrukcje dla epokorków, używając B {}, L {} itd. Do pogrubienia, łączenia i tym podobnych, i używania @param, @return, @raise itp. W celu wyjaśnienia wejścia, wyjścia, wyjątków i polubień.

Teraz, gdy przełączam się na sfinks, tracę wszystkie te funkcje. Czy istnieje automatyczny sposób przekształcania docstrukcji sformatowanych dla epokorków na docstrings sformatowany dla sfinksa?

Answer 1

Aby rozwinąć odpowiedź Kevina Horn'a, docstrings można przetłumaczyć w locie w procedurze obsługi zdarzeń wywołanej zdarzeniem autodoc-process-docstring.

Poniżej znajduje się mały pokaz (spróbuj go, dodając kod do conf.py). Zastępuje on znak @ w jakimś wspólnym Epytext fields z :, który jest używany w odpowiednim Sphinx fields.

import re 

re_field = re.compile('@(param|type|rtype|return)') 

def fix_docstring(app, what, name, obj, options, lines): 
    for i in xrange(len(lines)): 
     lines[i] = re_field.sub(r':\1', lines[i]) 

def setup(app): 
    app.connect('autodoc-process-docstring', fix_docstring) 

Answer 2

Teoretycznie można napisać rozszerzenie Sphinx, które złapie każde zdarzenie zostanie wywołane, gdy docstring zostanie odczytany (source_read, może?) I przetłumaczyć docstrukcje w locie.

mówię teoretycznie, ponieważ:

1. byłem zamiar napisać coś takiego przez bardzo długi czas, ale nie udało się obejść z nim jeszcze.
2. Tłumaczenie takich tekstów jest zawsze trudniejsze niż się wydaje.

Prawdopodobnie możesz spróbować po prostu zastąpić wszystkie docstrukcje w kodzie podobnym tłumaczem spoza Sfinksa, być może używając modułu ast lub czegoś podobnego.

Answer 3

Pyment jest narzędziem, które może konwertować docstrings Python i stworzyć brakujące jedynek szkielety. Może zarządzać Google, Epydoc (w stylu javadoc), Numpydoc, reStructuredText (reszta domyślnie Sphinx) formaty docstring.

Akceptuje pojedynczy plik lub folder (przeglądanie także podfolderów). Dla każdego pliku rozpozna każdy format docstrukcji i przekształci go w pożądany. Na końcu zostanie wygenerowana łatka, która zostanie zastosowana do pliku.

Aby przekształcić swój projekt:

• zainstalować opłatą pokrywającą

Wpisz następujące (można użyć virtualenv):

$ git clone https://github.com/dadadel/pyment.git 
$ cd pyment 
$ python setup.py install 

• przekonwertować z Epydoc do Sphinx

można przekształcić swój projekt do formatu Sphinx (reszta), który jest domyślny format, wykonując:

$ pyment /my/folder/project