Python 문서화를위한 reStructuredText의 실제 대안이 있습니까?

Question

오픈 소스 Python 프로젝트를 곧 시작하고 문서화 문자열을 작성하는 방법을 미리 결정하려고합니다. 분명한 대답은 autodoc을 사용하여 reStructuredText와 Sphinx를 사용하는 것입니다. 왜냐하면 I 정말은 내 문서 문자열에 내 코드를 올바르게 문서화 한 다음 Sphinx가 자동으로 API 문서를 구성하기 때문입니다.

문제는 사용하는 reStructuredText 구문입니다. 렌더링되기 전에 완전히 읽을 수없는 것 같습니다. 예를 들어 :

 
: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 

당신은 에 정말 천천히 그 구문 뒤범벅에서 어떤 의미를 만들기 위해 분 정도 걸릴 수 있습니다.

 
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 

방법 좋네요 : 나는 훨씬 더 다음과 같습니다 위의 대응 구글 방법 (Google Python Style Guide)를, 좋아! 그러나 물론, 스핑크스는 그 중 하나도 가지지 않을 것이고, "Args :"뒤에 모든 텍스트를 하나의 긴 줄로 표현할 것입니다.

그래서 요약하기 전에이 reStructuredText 구문을 사용하여 코드베이스를 더럽 히기 전에 필자 자신의 API doc을 작성하는 것만으로도 스핑크스와 스핑크스를 사용하는 것에 대한 실질적인 대안이 있는지 알고 싶습니다. 예를 들어 Google Style Guide의 문서화 스타일을 처리하는 Sphinx 확장 프로그램이 있습니까?

Answer 1

저는 현재 파이썬 프로젝트를 문서화하는 데있어 sphinx보다 나은 것을 생각하지 않습니다.

가장 좋아하는 선택을 sphinx과 함께 사용하려면 을 사용하십시오.

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 

이 (전체 예 Here이다), HTML 출력이 this

처럼 나는 첫 번째 파일의 구조가 명확하고 읽기 쉽게 생각하는 모양 : 당신의 예를 바탕으로이 같을 것이다. guide에는 몇 가지 추가 정보와 규칙이 나와 있습니다. numpydoc 확장 프로그램은 autodoc에서도 작동합니다.

Answer 2

파이썬은 docstring의 내용을/class/variable 객체 function에 첨부 된 __doc__ 속성으로 사용할 수 있도록합니다.

그래서, 원하는 형식으로 된 문서를 좋아하는 형식으로 변환하는 Python 프로그램을 쉽게 작성할 수 있습니다. Javadoc 스타일링이나 XML을 사용할 수도 있습니다.

덧붙여서 Sphinx는 Python으로 작성 되었기 때문에 RST가 아닌 입력을받는 것은 단지 작은 양의 Python 코드를 작성하는 문제 일뿐입니다.

Answer 3

실제로 reStructuredText과 PEP8의 스타일 가이드는 대다수의 제 3 자 프로그래머가이를 준수하지만 Python의 표준 라이브러리 자체를 코딩하는 데 주로 적용됩니다.

나는 Google의 인수 스타일이 코드 관점에서 훨씬 낫다는 것에 동의합니다. 하지만 generate such docstring with sphinx도 가능합니다. with the new lines and indentation preserved. 그래도 with a more sphinxy formatting처럼 출력되지 않습니다.

어쨌든, 은에 스핑크스를 사용해야하고, 그런데 autodoc 스핑크스 모듈은 확실히 작은 부분입니다. Epydoc (epytext 및 reStructuredText, Javadoc or Plaintext을 지원) 또는 pydoctor과 같은 문서 문자열의 내용을 검색 할 수있는 문서 생성기 또는 사실 Doxygen과 같은 보편적 인 문서 생성기를 사용할 수 있습니다.

확실히 스핑크스는 매우 pythonic이며, Python과 함께 사용하면 매우 편리하며 코드를 파이썬의 생태계와 일관되게 만들 수 있습니다. 나는 당신이 not the only one이라고 생각하는데, 이것이 "부족하다"고 생각합니다. 어쩌면 그들은이 불만 사항을 미래에 고려해야 할 것입니다. 아니면 autodoc 모듈을 혼자서 modyfying하는 것을 고려해 볼 수도 있습니다. 매우 어렵지 않아야합니다. 파이썬에서는 좋은 연습이 될 것입니다.

Answer 4

원하는 형식으로 docstrings을 작성할 수 있습니다. 그러나 다른 모든 Python 프로그래머를 위해 이미 알고있는 마크 업과 도구를 사용하는 것이 가장 좋습니다. reST와 스핑크스를 계속 사용하면 삶이 더 쉬워집니다.

Answer 5

스 픽스가 아닌 epydoc을 사용합니다. 따라서이 답변이 적용되지 않을 수 있습니다.

메서드 및 함수를 문서화하기 위해 설명하는 reStructuredText 구문 만 가능한 것은 아닙니다. sphix가 지원하는 경우 내가 시도 할

: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 

: 지금까지, 나는 구글의 방식과 매우 유사한 consolidated definition list를 사용하여 매개 변수를 설명 선호합니다. 그렇지 않다면 (비록 지금 당장 능동적이지는 않지만) epydoc을 사용하는 것을 고려해보십시오.

Answer 6

새 줄을 시작하고 각 변수 이름 뒤에 탭을 추가하기 만하면됩니다. 그 다음은 consucutive 굵은 변수 이름으로 여러 줄에 렌더링 :

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 

Answer 7

나는 구글 스타일과 NumPy와 스타일의 문서화 문자열 모두를 분석, 표준 reStructuredText로 변환하는 Sphinx extension을 만들었습니다.

$ pip install sphinxcontrib-napoleon 

을 그리고 conf.py에서 활성화 :

를 사용하려면 설치

# conf.py 

# Add autodoc and napoleon to the extensions list 
extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.napoleon'] 

더 많은 문서를 나폴레옹 here에.