Python 문서 용 reStructuredText에 대한 실제 대안이 있습니까?

Python 문서 용 reStructuredText에 대한 실제 대안이 있습니까?

---

곧 오픈 소스 Python 프로젝트를 시작하고 있으며 문서화 문자열을 작성하는 방법을 미리 결정하려고합니다. 분명한 대답은 autodoc과 함께 reStructuredText와 Sphinx를 사용하는 것입니다. 왜냐하면 저는 독 스트링에 내 코드를 적절하게 문서화 한 다음 Sphinx가 자동으로 API 문서를 생성하도록하는 아이디어를 정말 좋아 하기 때문 입니다.

문제는 그것이 사용하는 reStructuredText 구문입니다. 렌더링되기 전에는 완전히 읽을 수 없다고 생각합니다. 예를 들면 :

: param path : 래핑 할 파일의 경로
: 유형 경로 : str
: param field_storage : 래핑 할 : class :`FileStorage` 인스턴스
: type field_storage : FileStorage
: param temporary : File 인스턴스가 삭제 될 때 파일 삭제 여부
    파괴되었다
: 임시 유형 : bool

당신은 정말로 속도를 늦추고 그 구문의 뒤죽박죽을 이해하기 위해 잠시 시간을 내야합니다. Google 방식 ( Google Python Style Guide )이 훨씬 더 마음에 듭니다. 위의 내용은 다음과 같습니다.

Args :
    경로 (str) : 래핑 할 파일의 경로
    field_storage (FileStorage) : 래핑 할 FileStorage 인스턴스
    임시 (bool) : 파일 삭제시 파일 삭제 여부
        인스턴스가 파괴되었습니다

웨이 좋네요! 그러나 물론 Sphinx는 그런 것이 없으며 "Args :"뒤에있는 모든 텍스트를 한 줄로 렌더링합니다.

요약하자면,이 reStructuredText 구문으로 코드베이스를 더럽 히기 전에 API 문서를 작성하는 것 외에는이 코드와 스핑크스를 사용하는 것에 대한 실제 대안이 있는지 알고 싶습니다. 예를 들어 Google 스타일 가이드의 독 스트링 스타일을 처리하는 Sphinx 용 확장 프로그램이 있습니까?

---

Google 스타일과 NumPy 스타일 독 스트링을 모두 구문 분석하고 표준 reStructuredText로 변환 하는 Sphinx 확장 프로그램 을 만들었습니다 .

사용하려면 간단히 설치하십시오.

$ pip install sphinxcontrib-napoleon 

그리고 conf.py에서 활성화하십시오.

# conf.py

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

나폴레옹에 대한 더 많은 문서는 여기 .

---

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

나의 마음에 드는 선택이 사용하는 명확하게 문서화 문자열이하는 방법 sphinx과 함께를 numpydoc. 귀하의 예에 따르면 다음과 같습니다.

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 출력은 다음과 같습니다.

첫 번째 파일의 구조가 더 명확하고 읽기 쉽다고 생각합니다. 가이드는 더 많은 정보와 규칙 일부를 제공합니다. numpydoc확장과 함께 작동 autodoc뿐만 아니라.

---

나는 스핑크스가 아닌 epydoc을 사용 하므로이 답변이 적용되지 않을 수 있습니다.

메서드와 함수를 문서화하기 위해 설명하는 reStructuredText 구문 만이 가능한 것은 아닙니다. 지금까지 Google 방식과 매우 유사한 통합 정의 목록을 사용하여 매개 변수를 설명하는 것을 선호합니다 .

: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

I would try out if sphix supports it. If it doesn't you may also consider using epydoc just for that (although it is not that actively maintaned right now).

---

Actually, reStructuredText as well as the style guide from PEP8 apply mostly for coding the Python's standard library itself, albeit a lot of third party programmers conform to that as well.

I agree with you that the Google's style for arguments is much better from an in-code perspective. But you should be able to generate such docstring with sphinx as well, with the new lines and indentation preserved. It doesn't output as nice as with a more sphinxy formatting though.

Anyway, you don't have to use sphinx, and by the way, the autodoc module of sphinx is definitely just a small part of it. You can virtually use any documentation generator which is capable of retrieving the content of docstrings, like Epydoc (which support epytext as well as reStructuredText, Javadoc or Plaintext) or pydoctor, or even a more universal one like Doxygen.

But definitely, sphinx is quite pythonic, very convenient to use with Python, and make your code consistent with the Python's ecosystem. I think you are not the only one who think this is a "lack". Maybe they will take these complaints into account in the future, or maybe you might even consider modyfying the autodoc module by yourself, should not be very difficult, it's in Python, it would be a good exercise.

---

You can write docstrings in any format you like. However, for the sake of every other Python programmer, it's best to use markup and tools that they already know. Their lives is easier if you stick to reST and Sphinx.

---

Python makes the contents of the docstrings available as a __doc__ attribute attached to the function/class/variable object.

So, you could trivially write a Python program which converts the documentation from whatever format you like into whatever format you like. You could even use Javadoc styling, or XML, or whatever.

Incidentally, since Sphinx is written in Python, making it take non-RST input is just a matter of writing a small amount of Python code.

---

you just need to start a new line and add a tap after each variable name. Then it is rendered in several lines with consucutive bold variable names:

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

ReferenceURL : https://stackoverflow.com/questions/11163436/are-there-any-real-alternatives-to-restructuredtext-for-python-documentation