모듈을 리팩토링과 <code>pack.foo.Bar</code> 클래스 제공하는 파이썬 패키지 <code>pack</code>을 감안할 때 intersphinx

Question

포함한 이전 버전과의 호환성을 유지하십시오 Bar 클래스로 이동되도록

pack/ 
    __init__.py # empty 
    foo.py 
   # content of foo.py 
     """ 
     This module does stuff using the :class:`pack.foo.Bar` class. 
     """ 

     class Bar(object): 
      pass 

     # much more code here 

내가, 패키지에 pack.foo 모듈을 리팩토링 할을 pack/foo/bar.py 파일 이전 버전과의 호환성을 유지하기 위해, 나는 pack/foo/__init__.py 파일이 한 수의 API

""" 
This module does stuff using the :class:`pack.foo.Bar` class. 
""" 

from pack.foo.bar import Bar 
__all__ = ['Bar'] 

사용자는 여전히 from pack.foo import Bar를 사용할 수 있습니다.

한 가지 문제가 남아 있습니다. 스핑크스를 사용할 때의 참고 사항입니다. intersphinx 확장자를 사용하는 경우 사용자가 만든 문서를 끊을

WARNING: py:class reference target not found pack.foo.bar.Bar 

: 스핑크스가 pack/foo/__init__.py에 문서화 문자열을 구문 분석 할 때 대상을 찾을 수 없습니다.

스핑크스 객체 인벤토리를 포함하여 패키지 구조를 리팩토링하고 완전한 하위 호환성을 유지하는 적절한 방법은 무엇입니까?

Answer 1

다음은 몇 가지 조사 결과입니다.

이 상황에서는 은색 총알이 없습니다.

먼저, sphinx-apidoc에 의해 생성 된 코드 문서는 모듈 레이아웃이 파일 레이아웃을 따를 것입니다. 즉, pack/foo.py에 정의 된 Bar 클래스는 pack/__init__.py에서 어떤 import mangling이 발생하더라도 상관없이 pack.foo.Bar으로 기록됩니다.

둘째, 여전히 autodoc extension을 사용할 수 있습니다. Autodoc은 구조화 된 텍스트에서 정의 된대로 문서화 된 심볼을 normaly로 가져 오기만하면됩니다. 이런 식으로, 당신은 비록 캐치가있다

.. autoclass:: pack.Bar 
    :members: 

사용하여 Bar 클래스에 대한 HTML 문서를 생성 할 수있다. 모든 문서화 된 기호 (및 각 종속성, 전이)는 문서화되기 위해 의도 된 동일한 네임 스페이스와 함께 사용해야합니다. 추가 클래스를 Baz를 제공, 우리의 예제의 변화를 고려 : 그것은 단지 pack.Bar로 인해 pack/__init__.py의 내용을 가져올 수 있기 때문에

이

pack/ 
    __init__.py 
     # content of __init__.py 
   from pack.foo.bar import Bar, Baz 
     __all__ = ['Bar', 'Baz'] 

    foo.py 
     # content of foo.py 
     """ 
     This module does stuff using the :class:`pack.foo.Bar` class. 
     """ 

     class Bar(object): 
      pass 

     class Baz(Bar): # Here, sphinx thinks that Baz inherits from 
      pass   # pack.foo.Bar because Bar.__module__ is 
         # pack.foo in this context. 

스핑크스가 pack.foo.Bar를 가져올 실패합니다.

이 작업을 수행하려면 API의 코드 자체에서 패키지 API가 제공하는 정확한 가져 오기 레이아웃 만 사용하는 방법을 찾아야합니다. 예를 들어, Bar 및 Baz 클래스를 별도의 파일로 정의하면이 작업을 수행 할 수 있습니다. 행운을 빌며주기적인 수입에주의하십시오!