나는 여러 개의 전역 상수가 정의 된 모듈 errors.py을 가지고있다. (참고 : 파이썬에는 상수가 없다는 것을 이해하지만 대문자로 규칙을 정의했다.)파이썬에서 모듈 상수를 문서화하는 방법은 무엇입니까?
"""Indicates some unknown error."""
API_ERROR = 1
"""Indicates that the request was bad in some way."""
BAD_REQUEST = 2
"""Indicates that the request is missing required parameters."""
MISSING_PARAMS = 3
reStructuredText를 사용하여 어떻게 이러한 상수를 문서화 할 수 있습니까? 보시다시피, 위에 문서화 문자열을 나열했지만, 그렇게 할 수있는 문서를 찾지 못했습니다. 단지 추측으로 만했습니다.
불행히도 변수 (및 상수)에는 문서화 문자열이 없습니다. 결국, 변수는 정수의 이름 일 뿐이며 함수 또는 클래스 객체에 대한 방법으로 숫자 1에 문서화 문자열을 첨부하지 않으려 고합니다.
stdlib의 거의 모든 모듈을 보면 pickle과 같이 사용하는 유일한 설명은 주석입니다. 그리고 네, 그 help(pickle) 만이 표시됩니다 것을 의미합니다 :
DATA
APPEND = b'a'
APPENDS = b'e'
…
을 ... 완전히 의견을 무시. 문서가 내장 도움말에 나타나게하려면 모듈의 문서 문자열에 문서를 추가해야합니다.
하지만 스핑크스는 기본 제공 도움말보다 더 많은 작업을 수행 할 수 있습니다. 상수에 주석을 추출하도록 구성하거나 autodata을 사용하여 반자동으로 설정할 수 있습니다. 예를 들어 : #: 라인 어떤 할당 문 앞에
#: Indicates some unknown error.
API_ERROR = 1
다중, 또는 문 오른쪽에 하나의 #: 코멘트 효과적으로 객체에 대한 문서화 문자열이 autodoc에 의해 포착과 같은 작동합니다. 인라인 rST를 처리하고, 변수 이름에 대해 rST 헤더를 자동 생성합니다. 그 일을하기 위해해야 할 일은별로 없습니다.
,이 같은 별도의 상수 대신 enum 사용을 고려할 수 있습니다. Python 3.4를 사용하고 있지 않다면 (아마도 아직은 ...), 3.2+ 또는 flufl.enum에 대한 backport.enum 패키지가 있습니다 (동일하지는 않지만 유사합니다. stdlib 모듈의 주요 영감 이었기 때문입니다).) 2.6 이상.
(안 flufl.enum하지만 다음 stdlib/백 포트 버전) 열거 인스턴스도 문서화 문자열을 가질 수 있습니다 : 그들은 불행하게도 help(MyErrors.MISSING_PARAMS)에 표시되지 않지만
class MyErrors(enum.Enum):
"""Indicates some unknown error."""
API_ERROR = 1
"""Indicates that the request was bad in some way."""
BAD_REQUEST = 2
"""Indicates that the request is missing required parameters."""
MISSING_PARAMS = 3
, 그들은 스핑크스 autodoc가 선택할 수 문서화 문자열입니다.
해시 + 콜론을 사용하여 속성 (클래스 또는 모듈 수준)을 문서화 할 수 있습니다.
#: Use this content as input for moo to do bar
MY_CONSTANT = "foo"
이 일부 문서 발전기를 집어됩니다.
여기예는 찾을 수 없습니다 더 나은 하나 Sphinx document module properties
당신이 변수 후 문자열을 를 넣어 경우, 스핑크스는 변수의 문서로를 선택합니다. 나는 그것이 온통 그것을하기 때문에 그것이 효과가 있다는 것을 안다. 이와 같이 :
FOO = 1 """ Constant signifying foo. Blah blah blah... """ # pylint: disable=W0105 pylint 지시문은 설명서에 아무런 효과가없는 것으로 플래그를 지정하지 않도록 지시합니다.
에 도움이 될 것이며이 새로운 주석 => .. autodata :: FOO : annotation : ... http://sphinx-doc.org/ext를 참조하십시오. /autodoc.html#directive-autoattribute – macm
이전 질문이지만 관련 답변이 누락되었습니다.
또는 모듈의 문서 문자열에 .. py:data::을 통해 상수에 대한 설명을 포함 할 수 있습니다. 그렇게하면 문서가 대화 형 도움말을 통해 제공됩니다. 스핑크스는 이것을 멋지게 표현할 것입니다.
"""
Docstring for my module.
.. data:: API_ERROR
Indicates some unknown error.
.. data:: BAD_REQUEST
Indicates that the request was bad in some way.
.. data:: MISSING_PARAMS
Indicates that the request is missing required parameters.
"""
"이 상수를 어떻게 문서화 할 수 있습니까?" 주석 (또는 귀하의 경우에 문자열)을 추가하는 것은 이미 문서 형식입니다. sphinx-autodoc으로 내부 문서를 인식하고이를 스핑크스 출력물에 표시하는 방법을 묻고 있습니까? – mgilson