Czy istnieją realne alternatywy dla reStructuredText dla dokumentacji Pythona? [zamknięte]
Wkrótce zaczynam projekt open source Pythona i staram się z góry zdecydować, jak napisać moje docstringi. Oczywistą odpowiedzią byłoby użycie reStructuredText i Sphinx z autodoc, ponieważ ja naprawdę podoba mi się pomysł po prostu poprawnego dokumentowania mojego kodu w moich docstrings, a następnie Sphinx automatycznie konstruuje dla mnie dokument API.
Problemem jest składnia reStructuredText, której używa - myślę, że jest całkowicie nieczytelna przed renderowaniem. Na instancja:
:param path: The path of the file to wrap
:type path: str
:param field_storage: The :class:`FileStorage` instance to wrap
:type field_storage: FileStorage
:param temporary: Whether or not to delete the file when the File instance
is destructed
:type temporary: bool
Musisz naprawdę zwolnić i poświęcić chwilę, aby wydobyć jakikolwiek sens z tej składniowej pomyłki. Bardziej podoba mi się sposób Google (Google Python Style Guide ), który odpowiednik powyższego wygląda tak:
Args:
path (str): The path of the file to wrap
field_storage (FileStorage): The FileStorage instance to wrap
temporary (bool): Whether or not to delete the file when the File
instance is destructed
Sposób ładniejszy! Ale oczywiście Sphinx nie będzie miał tego i renderuje cały tekst po "Args:" w jednej długiej linii.
Więc podsumowując-zanim pójdę i zbezczeszczę bazę kodu tą składnią reStructuredText I chciałbym wiedzieć, czy są jakieś realne alternatywy dla korzystania z niego i Sphinx, poza pisaniem własnego dokumentu API. Na przykład, czy istnieje rozszerzenie dla Sphinx, które obsługuje styl docstring Google Style Guide?
7 answers
Nie wydaje mi się, aby w tej chwili było coś lepszego niż sphinx do dokumentowania projektów Pythona.
Aby mieć jaśniejszy docstring, moim ulubionym wyborem jest użycie sphinx razem z numpydoc. Na podstawie Twojego przykładu wyglądałoby to tak:
def foo(path, field_storage, temporary):
"""This is function foo
Parameters
----------
path : str
The path of the file to wrap
field_storage : :class:`FileStorage`
The :class:`FileStorage` instance to wrap
temporary : bool
Whether or not to delete the file when the File instance
is destructed
Returns
-------
describe : type
Explanation
...
Examples
--------
These are written in doctest format, and should illustrate how to
use the function.
>>> a=[1,2,3]
>>> print [x + 3 for x in a]
[4, 5, 6]
...
"""
pass
(pełny przykład to tutaj ), Wyjście HTML będzie wyglądało tak: this
Myślę, że struktura pliku rst jest jaśniejsza i bardziej czytelna. Poradnik zawiera więcej informacji i konwencje. Rozszerzenie numpydoc działa również z autodoc.
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/doraprojects.net/template/agent.layouts/content.php on line 54
2012-07-25 20:39:39
Stworzyłem rozszerzenie Sphinx , które parsuje zarówno docstringi Google style jak i NumPy style i konwertuje je na standardowe reStructuredText.
Aby go użyć, po prostu zainstaluj:
$ pip install sphinxcontrib-napoleon
I włączyć go w conf.py:
# conf.py
# Add autodoc and napoleon to the extensions list
extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.napoleon']
Więcej dokumentacji o Napoleonie tutaj .
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/doraprojects.net/template/agent.layouts/content.php on line 54
2013-07-26 20:36:57
Używam epydoc , a nie sphinx, więc ta odpowiedź może nie mieć zastosowania.
Opisywana przez Ciebie składnia reStructuredText do dokumentowania metod i funkcji nie jest jedyną możliwą. Zdecydowanie wolę opisywać parametry za pomocą skonsolidowanej listy definicji , która jest bardzo podobna do Google way:
:Parameters:
path : str
The path of the file to wrap
field_storage: FileStorage
The FileStorage instance to wrap
temporary: bool
Whether or not to delete the file when the File instance is destructed
Wypróbowałbym, czy sphix go wspiera. Jeśli nie, możesz również rozważyć użycie epydoc tylko do tego (chociaż nie jest to tak aktywnie utrzymywane prawo teraz).
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/doraprojects.net/template/agent.layouts/content.php on line 54
2012-06-23 09:32:56
Właściwie, reStructuredText jak również przewodnik po stylach z PEP8 stosuje się głównie do kodowania samej biblioteki standardowej Pythona, chociaż wielu programistów innych firm również się z tym zgadza.
Zgadzam się z Tobą, że styl Google dla argumentów jest znacznie lepszy z punktu widzenia kodu. Ale powinieneś być w stanie wygenerować taki docstring z sphinx , z nowymi liniami i zachowanymi wcięciami . Nie wychodzi tak ładnie jak z bardziej rozbudowanym formatowaniem.
W każdym razie, nie musisz używać sphinx, a przy okazji, moduł autodoc sphinx jest zdecydowanie tylko niewielką jego częścią. Możesz praktycznie użyć dowolnego generatora dokumentacji, który jest w stanie pobrać zawartość docstrings, jak Epydoc (który obsługuje epytext jak również reStructuredText, Javadoc lub Plaintext ) lub pydoctor , lub nawet bardziej uniwersalny jak Doxygen .
Ale zdecydowanie, sphinx jest dość pythonic , bardzo wygodny w użyciu z Pythonem, i sprawić, że Twój kod będzie zgodny z ekosystemem Pythona. Myślę, że nie jesteś jedyną osobą, która uważa to za "brak". Może uwzględnią te skargi w przyszłości, a może nawet rozważysz samodzielne modyfikowanie autodoc modułu, nie powinno być bardzo trudne, jest w Pythonie, byłoby to dobre ćwiczenie.
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/doraprojects.net/template/agent.layouts/content.php on line 54
2012-06-23 08:55:01
Możesz pisać docstringi w dowolnym formacie. Jednak ze względu na innych programistów Pythona najlepiej jest używać znaczników i narzędzi, które już znają. Ich życie jest łatwiejsze, jeśli trzymać się odpoczynku i Sfinksa.
Python udostępnia zawartość docstrings jako atrybut __doc__ dołączony do obiektu function/class / variable.
Możesz więc trywialnie napisać program Pythona, który konwertuje dokumentację z dowolnego formatu, który lubisz, na dowolny format. Możesz nawet użyć Javadoc styling, lub XML, lub cokolwiek innego.
Nawiasem mówiąc, ponieważ Sphinx jest napisany w Pythonie, zmuszenie go do wejścia non-RST jest tylko kwestią napisania niewielkiej ilości kodu Pythona.
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/doraprojects.net/template/agent.layouts/content.php on line 54
2012-06-23 07:26:42
Wystarczy uruchomić nową linię I dodać kranu po każdej nazwie zmiennej. Następnie jest renderowany w kilku wierszach z consucutive pogrubionymi nazwami zmiennych:
Args:
path (str):
The path of the file to wrap
field_storage (FileStorage):
The FileStorage instance to wrap
temporary (bool):
Whether or not to delete the file when the File
instance is destructed
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/doraprojects.net/template/agent.layouts/content.php on line 54
2012-07-15 13:00:21