Sphinx를 Cython과 함께 사용하려면 어떻게해야합니까?

Question

저는 최근에 모든 모듈 (최상위 레벨을 제외한 __init__.py 제외)을 *.pyx으로 바꾸고 ext_modules = [Extension('foo', ['foo.pyx'])]을 setup.py에 넣음으로써 광산 프로젝트를 Cythonized했습니다. 빌드 및 설치가 정상적으로 작동합니다. 그러나 cd doc; make html을 실행하면 Sfxx는 현재 *.pyx 인 모듈을 가져올 수 없으므로 실패합니다.

내가 doc/conf.py을 편집하고 sys.path.insert(0, os.path.abspath('../build/temp.linux-x86_64-2.7'))에 sys.path.insert(0, os.path.abspath('..'))을 변경하는 경우

후 스핑크스는 모든 모듈을 찾을 수 있으며, 문서를 생성 할 수 있지만,이 경우에 나는 error while formatting arguments for foo.bar: <built-in function bar> is not a Python function 같은 오류를 얻을. 아마도 이것은 스핑크스가 소스 파일이 아닌 *.so 파일에만 액세스 할 수 있기 때문일 수 있습니다. 같은 sys.path 수정은 또한 스핑크스 ( make doctest)를 통해 doctests를 실행할 수 있습니다.

내가 시도한 다른 해결책은 대신 *.py (그리고 에서 ext_modules = [Extension('foo', ['foo.py'])])을 사용하는 것이 었습니다. 이 경우 문서가 올바르게 빌드되지만 doctest는 이제 Cython을 우회합니다.

스핑크스와 Cython을 함께 사용하는 것과 관련된 온라인 정보를 찾을 수 없었습니다. 두 가지를 모두 사용하는 프로젝트의 소스 코드를 살펴 보았지만 *.pyx 파일의 docstrings을 사용하지 않는 것 같습니다. 나는 현자가 알고있다. 그러나 그 프로젝트는 너무 복잡해서 따로 골라 낼 수 없다.

스핑크스는 Cython 파일에서 docstrings을 지원합니까? 그렇다면이 작업을 어떻게 수행합니까?

Answer 1

더 나은 대답을 남겨두면 좋겠지 만, 여기에 제가 발견 한 해결 방법이 있습니다.

dipy 프로젝트는 doc/conf.py에서 직접 모듈을 가져옵니다. 모듈을 먼저 설치해야하지만 가져 오기 오류가 수정됩니다 (doctest는 Cython 화 된 파일에서 실행됩니다).

그러나 아직 error while formatting arguments 문제가 있습니다. 먼저 메서드/함수 시그니처를 *.so 파일에 포함 시키도록 Cython에 지시해야합니다. embedsignature Cython 지시문을 설정하여이 작업을 수행하십시오. dipy 프로젝트는 각 *.pyx 파일에이 값을 설정하지만 setup.py (이 설정 방법은 Cython 설명서 참조)으로 설정할 수도 있습니다. 이것은 여전히 ​​Sphinx 문서에 메소드 서명을 넣지 않습니다! 메서드 시그니처 문제에 대한 버그 보고서와 패치가 here입니다. 현재 Sphinx의 최신 버전 (1.1.3)에는 아직 포함되어 있지 않지만 개발 저장소에서 Sphinx를 설치하면 작동합니다.

Answer 2

여기서 혼란스러워 보이는 부분이 있습니다. 스핑크스는 실제로 구문 분석기가 아닙니다. 스핑크스가 문서 문자열을 잡을 수있게하려면 Python 코드를 실행 가능하게 만들어야합니다. 이것이 확장 파일의 이름을 ".py"로 바꾸는 것이 도움이되지 않는 이유입니다.

글쎄, 최근에 스핑크스와 Cython으로 일해 왔고 내 경험을 공유하고 싶습니다 ... 다음은 docstrings에서 주어진 컴파일 된 Cython 확장에 대한 HTML 문서의 자동화 된 생성을 얻는 전체 절차입니다 :

[참고 : 나는 스핑크스 1.1.3와 사이 썬 0.17.4 사용]이 가질 수있는 모든 제한 사항 (모든

첫째, 파이썬의 "문서화 문자열"를 사용 - 예에 의해, 당신은 설명 할 수없는 생성자.

cdef class PyLabNode: 
    """ 
    This is a LabNode !!! 
    """ 
    cdef LabNode* thisptr 
    cdef PyLabNetwork network 

    def __cinit__(self): 
     self.thisptr = new LabNode() 

    def __dealloc__(self): 
     if self.thisptr: 
      del self.thisptr 

    def SetNetwork(self, PyLabNetwork net): 
     """ 
     Set the network !!! 
     """ 
     self.network = net 

을 그리고 "yourextension.so"다시 컴파일 : 당신의 사이 썬 코드에 docstrings 사양)를 참조하십시오.

그런 다음 "sphinx-quickstart"를 실행하고 질문에 답하십시오. "autodoc"을 묻는 질문에 yes라고 대답하는 것을 잊지 마십시오. 이렇게하면 "Makefile", "index.rst"파일 및 "conf.py"파일이 생성됩니다.

이 마지막 "conf.py는"모듈을 찾을 수 있었다 스핑크스에게 편집 할 수 있습니다

# If extensions (or modules to document with autodoc) are in another directory, 
# add these directories to sys.path here. If the directory is relative to the 
# documentation root, use os.path.abspath to make it absolute, like shown here. 
#sys.path.insert(0, os.path.abspath('.')) 
sys.path.insert(0, os.path.abspath('../../parent/dir/of/yourextension/')) 

은 "index.rst"파일이 될 수있는 모듈을 말할뿐만 아니라 편집 할 수있다 분석 :

$ make html 

것은 나를 위해 충분했다 그 :

Contents: 

.. toctree:: 
    :maxdepth: 2 


.. automodule:: yourextension 
    :members: 
    :undoc-members: 
    :show-inheritance: 

마지막으로 수행하여 문서를 구축 (".../_ build/html /"디렉토리에 html 파일의 결과 세트가 있습니다.) 이전 질문에서 스핑크스와 싸이언이 진화 해 왔을 지 모르지만 나는 처리 할 "서명"문제가 없었습니다. 특정 Cython 지시문을 사용하거나 스핑크스에 적용 할 수정 사항이 없습니다 ...

희망이 도움이됩니다.

편집 : 음, 내 말을 되찾고 싶습니다. Epydoc을 사용하는 동안 "댄"이 "embedsignature"문제에 관해 언급 한 문제가 발생했습니다 (이 문제는 스핑크스와 관련된 문제이기도합니다). 이 컴파일러 지시문 어쨌든 파이썬을 준수 서명을 보내지 않습니다 활성화 :

PyLabNode.SetNetwork(self, PyLabNetwork net) 

이 2 단점이있다 : 클래스 접두사와 입력 매개 변수의 점 표기법을. 이 두 스핑크스을 도울 수

def SetNetwork(self, PyLabNetwork net): 
    """ 
    SetNetwork(self, net) 
    Set the net !!! 
    @param self: Handler to this. 
    @type self: L{PyLabNode} 
    @param net: The network this node belongs to. 
    @type net: L{PyLabNetwork} 
    """ 
    self.network = net 

희망 : 끝에

, 나는 올바른 사람을 보내 알아낼 수있는 유일한 방법은 지금과 같은 문서화 문자열의 첫 번째 줄에서 호환 서명을 작성했다 및

---

편집 Epydoc 사용자 ... :, 나는 Epidoc에 성공적으로 문서를 생성 할 수 __cinit__했다 관련된 (스핑크스와 시도하지 않았다)에 대한 설명을 두배로 이 같은 :

이 Golgauth는 설명

# For Epydoc only (only used for docstring) 
def __init__(self, sim): 
    """ 
    __init__(self, sim) 
    Constructor. 
    @param sim: The simulator this binding is attached to. 
    @type sim: L{PyLabSimulatorBase} 
    """ 

# Real Cython init 
def __cinit__(self, PyLabSimulatorBase sim): 
    self.thisptr = new LabNetBinding() 
    self.sites = [] 
    simulator = sim 

Answer 3

으로, 스핑크스의 autodoc 모듈은 .so 아닌 .pyx에서 문서화 문자열을합니다. 것이다

python setup.py build_ext --inplace 

그런 식의 autodoc : 파이썬 모듈을 cythonizing 때 스핑크스 구성을 변경하지 않고도 문서를 생성하는 가장 간단한 방법은 확장 모듈이 제자리에 당신이 문서를 생성하기 전에 간단하게 구축하는 것입니다 일반 파이썬 모듈과 함께 확장 모듈을 찾아 예상대로 문서를 생성 할 수 있습니다.

이전 sphinx-build을 실행하는이 단계는 확장 모듈을 구축 할 sphinx-quickstart에 의해 생성 된 Makefile을 편집 할 수 있습니다 잊어 위험하지 않으려면 :

스핑크스 소개

html: 
    @cd /path/to/setup.py; python setup.py build_ext --inplace 
    ...