Как я могу использовать расширение Sphinx Autodoc для частных методов?

Question

Я использую Sphinx для документирования своего проекта на Python. У меня включено расширение autodoc, и в моих документах указано следующее.

.. autoclass:: ClassName
   :members:

Проблема в том, что он документирует не приватные методы в классе Как включить приватные методы тоже?

Answer 1

, если вы используете sphinx 1.1 или выше, с сайта документации sphinx по адресу http://www.sphinx -doc.org / en / master / ext / autodoc.html ,

:special-members:
:private-members:

Answer 2

Один из способов обойти это - принудительно заставить Sphinx документировать приватных членов. Вы можете сделать это, добавив automethod в конец документации уровня класса:

class SmokeMonster(object):
   """
   A large smoke monster that protects the island.
   """
   def __init__(self,speed):
      """
      :param speed: Velocity in MPH of the smoke monster
      :type  speed: int

      .. document private functions
      .. automethod:: _evaporate
      """
      self.speed = speed

   def _evaporate(self):
      """
      Removes the smoke monster from reality. Not to be called by client.
      """
      pass

Answer 3

Вы можете добавить это в conf.py файл:

autodoc_default_flags = ['members', 'undoc-members', 'private-members', 'special-members', 'inherited-members', 'show-inheritance']

Answer 4

Глядя на код apidoc , мы можем изменить то, что sphinx-apidoc генерирует, устанавливая переменную среды:

export SPHINX_APIDOC_OPTIONS='members,special-members,private-members,undoc-members,show-inheritance'

Вы также можете добавить эту настройку в свой Makefile (если он используется в вашем пакете):

docs:
    rm -rf docs/api
    SPHINX_APIDOC_OPTIONS='members,special-members,private-members,undoc-members,show-inheritance' sphinx-apidoc -o docs/api/ intellprice
    $(MAKE) -C docs clean
    $(MAKE) -C docs html

Answer 5

Вы пытались использовать пользовательский метод для определения того, следует ли включать участника в документацию, используя autodoc-skip-member?

Answer 6

Нет, private означает приватность для класса, и его нельзя использовать из публичного API. Это не означает секрет, и для тех из нас, кто хочет использовать sphinx для полной документации классов, исключая частные методы, довольно раздражает.

Предыдущий ответ правильный. Вам придется использовать пользовательский метод, поскольку Sphinx в настоящее время не поддерживает autodoc в сочетании с закрытыми методами.

Answer 7

Вот подсказка: представьте, что личное означает «секрет».

Вот почему Сфинкс не документирует их.

Если вы не имеете в виду «секрет», подумайте об изменении их имен. Избегайте использования имени, начинающегося с подчеркивания; это не поможет, если у вас нет причин хранить секрет реализации.