blocks|key|1285870|text|如果您使用的是sphinx1.1或更高版本，请访问sphinx文档站点http://www.sphinx-doc.org/en/master/ext/autodoc.html，|type|unstyled|depth|inlineStyleRanges|entityRanges|offset|length|data|1285871|:special-members:
:private-members:|code-block|syntax|javascript|1285872|entityMap|0|LINK|mutability|MUTABLE|url|http://www.sphinx-doc.org/en/master/ext/autodoc.html^0|Z|1G|0|0|0^^$0|@$1|2|3|4|5|6|7|Q|8|@]|9|@$A|R|B|S|1|T]]|C|$]]|$1|D|3|E|5|F|7|U|8|@]|9|@]|C|$G|H]]|$1|I|3|-4|5|6|7|V|8|@]|9|@]|C|$]]]|J|$K|$5|L|M|N|C|$O|P]]]]

if you are using sphinx 1.1 or above, from the sphinx documentation site at <a href="http://www.sphinx-doc.org/en/master/ext/autodoc.html" rel="noreferrer">http://www.sphinx-doc.org/en/master/ext/autodoc.html</a>,

<pre><code>:special-members:
:private-members:
</code></pre>

blocks|key|1500805|text|您可以将其添加到conf.py文件中：|type|unstyled|depth|inlineStyleRanges|offset|length|style|CODE|entityRanges|data|1500806|autodoc_default_flags+=+['members',+'undoc-members',+'private-members',+'special-members',+'inherited-members',+'show-inheritance']|code-block|syntax|javascript|1500807|entityMap^0|8|7|0|0^^$0|@$1|2|3|4|5|6|7|M|8|@$9|N|A|O|B|C]]|D|@]|E|$]]|$1|F|3|G|5|H|7|P|8|@]|D|@]|E|$I|J]]|$1|K|3|-4|5|6|7|Q|8|@]|D|@]|E|$]]]|L|$]]

You can add this to <code>conf.py</code> file:

<pre><code>autodoc_default_flags = ['members', 'undoc-members', 'private-members', 'special-members', 'inherited-members', 'show-inheritance']
</code></pre>

blocks|key|1500652|text|解决这个问题的一种方法是显式地强制Sphinx记录私有成员。您可以通过将automethod附加到类级别文档的末尾来完成此操作：|type|unstyled|depth|inlineStyleRanges|offset|length|style|CODE|entityRanges|data|1500653|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|code-block|syntax|javascript|1500654|entityMap^0|10|A|0|0^^$0|@$1|2|3|4|5|6|7|M|8|@$9|N|A|O|B|C]]|D|@]|E|$]]|$1|F|3|G|5|H|7|P|8|@]|D|@]|E|$I|J]]|$1|K|3|-4|5|6|7|Q|8|@]|D|@]|E|$]]]|L|$]]

One way to get around this is to explicitly force Sphinx to document private members. You can do this by appending <code>automethod</code> to the end of the class level docs:

<pre><code>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
</code></pre>

blocks|key|1500520|text|您是否尝试过通过autodoc-skip-member使用custom+method来确定是否应将成员包括在文档中|type|unstyled|depth|inlineStyleRanges|offset|length|style|CODE|entityRanges|data|1500521|entityMap|0|LINK|mutability|MUTABLE|url|http://sphinx.pocoo.org/ext/autodoc.html#skipping-members^0|8|J|T|D|0|0^^$0|@$1|2|3|4|5|6|7|N|8|@$9|O|A|P|B|C]]|D|@$9|Q|A|R|1|S]]|E|$]]|$1|F|3|-4|5|6|7|T|8|@]|D|@]|E|$]]]|G|$H|$5|I|J|K|E|$L|M]]]]

Have you tried using a <a href="http://sphinx.pocoo.org/ext/autodoc.html#skipping-members" rel="nofollow noreferrer">custom method</a> for determining whether a member should be included in the documentation, using <code>autodoc-skip-member</code>?

blocks|key|1500748|text|查看apidoc+code，我们可以通过设置环境变量来更改sphinx-apidoc生成的内容：|type|unstyled|depth|inlineStyleRanges|entityRanges|offset|length|data|1500749|export+SPHINX_APIDOC_OPTIONS='members,special-members,private-members,undoc-members,show-inheritance'|code-block|syntax|javascript|1500750|您还可以将此设置添加到您的Makefile中(如果您的包使用了一个)：|1500751|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|1500752|entityMap|0|LINK|mutability|MUTABLE|url|https://github.com/sphinx-doc/sphinx/blob/master/sphinx/apidoc.py#L28^0|2|B|0|0|0|0|0^^$0|@$1|2|3|4|5|6|7|U|8|@]|9|@$A|V|B|W|1|X]]|C|$]]|$1|D|3|E|5|F|7|Y|8|@]|9|@]|C|$G|H]]|$1|I|3|J|5|6|7|Z|8|@]|9|@]|C|$]]|$1|K|3|L|5|F|7|10|8|@]|9|@]|C|$G|H]]|$1|M|3|-4|5|6|7|11|8|@]|9|@]|C|$]]]|N|$O|$5|P|Q|R|C|$S|T]]]]

Looking at <a href="https://github.com/sphinx-doc/sphinx/blob/master/sphinx/apidoc.py#L28" rel="nofollow">apidoc code</a>, we can change what sphinx-apidoc generate setting an environment variable:

<pre><code>export SPHINX_APIDOC_OPTIONS='members,special-members,private-members,undoc-members,show-inheritance'
</code></pre>

You can also add this setup into your Makefile (if your package uses one):

<pre><code>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
</code></pre>

blocks|key|1500613|text|不，private意味着类是私有的，不应该在公共API中使用它。这并不意味着秘密，对于我们中那些希望使用sphinx进行完整的类文档记录的人来说，排除私有方法是相当恼人的。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1500614|前面的答案是正确的。您将不得不使用自定义方法，因为Sphinx目前不支持autodoc与私有方法结合使用。|1500615|entityMap^0|0|0^^$0|@$1|2|3|4|5|6|7|F|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|G|8|@]|9|@]|A|$]]|$1|D|3|-4|5|6|7|H|8|@]|9|@]|A|$]]]|E|$]]

No, private means private to the class and that it shouldn't be used from the public API. It's not meant to mean secret and for those of us wishing to use sphinx for full documentation of classes, excluding private methods is rather annoying.

The previous answer is correct. You will have to use a custom method as Sphinx does not currently support autodoc in conjunction with private methods.

blocks|key|1286004|text|如果您只想记录特定的私有方法，而不是所有的私有方法，那么可以对每个方法使用automethod指令，而不是:private-members:。|type|unstyled|depth|inlineStyleRanges|offset|length|style|CODE|entityRanges|data|1286005|我经常使用与普通公共方法同名的前导下划线方法，该方法具有函数的实际实现。然后，公共方法对输入参数进行各种健全性检查。下划线方法跳过它们，因此可以调用它们以提高效率，但类型安全性较低。|1286006|例如(为抄袭他们的例子@cmcginty道歉)|1286007|class+SmokeMonster(object):
+++"""
+++A+large+smoke+monster+that+protects+the+island.
+++"""
+++def+__init__(self,+speed,+initial_position):
++++++"""
++++++:param+speed:+Velocity+in+MPH+of+the+smoke+monster
++++++:param+inital_position:+Position+of+the+smoke+monster
++++++"""
++++++self.speed+=+speed
++++++self.position+=+initial_position

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

+++def+fly_to(self,+position):
++++++"""
++++++Have+the+monster+fly+to+the+specified+position.

++++++:param+position:+Desired+location+for+the+monster+to+fly+to.
++++++"""
++++++if+not+position.is_valid():
++++++++++raise+ValueError("Invalid+position:+"+%2B+str(position))
++++++if+not+self.can_fly():
++++++++++raise+RuntimeError("Smoke+monster+is+not+currently+able+to+fly.")

++++++self._fly_to(position)

+++def+_fly_to(self,+position):
++++++"""Equivalent+to+:meth:`SmokeMonster.fly_to`,+but+without+the+safety+checks.

++++++Not+normally+recommended+for+end+users,+but+available+if+you+need+to
++++++improve+efficiency+of+the+`fly_to`+call+and+you+already+know+it+is+safe
++++++to+call.
++++++"""
++++++self.position+=+position|code-block|syntax|javascript|1286008|然后记录_fly_to，而不是_evaporate，您可以这样做：|1286009|..+autoclass::+SmokeMonster
++++:members:

++++..+automethod::+SmokeMonster._fly_to|1286010|entityMap^0|11|A|1H|H|0|0|0|0|4|7|F|A|0|0^^$0|@$1|2|3|4|5|6|7|U|8|@$9|V|A|W|B|C]|$9|X|A|Y|B|C]]|D|@]|E|$]]|$1|F|3|G|5|6|7|Z|8|@]|D|@]|E|$]]|$1|H|3|I|5|6|7|10|8|@]|D|@]|E|$]]|$1|J|3|K|5|L|7|11|8|@]|D|@]|E|$M|N]]|$1|O|3|P|5|6|7|12|8|@$9|13|A|14|B|C]|$9|15|A|16|B|C]]|D|@]|E|$]]|$1|Q|3|R|5|L|7|17|8|@]|D|@]|E|$M|N]]|$1|S|3|-4|5|6|7|18|8|@]|D|@]|E|$]]]|T|$]]

If you only want to document specific private methods, not all of them, you can use the <code>automethod</code> directive for each one, rather than <code>:private-members:</code>.

I often use leading underscore methods with the same name as a normal public method, which has the actual implementation of a function. The public method then has various sanity checks about the input arguments. The underscore method skips them, so they can be called for improved efficiency, but with less type safety.

E.g. (with apologies to @cmcginty for stealing their example)

<pre><code>class SmokeMonster(object):
 """
 A large smoke monster that protects the island.
 """
 def __init__(self, speed, initial_position):
 """
 :param speed: Velocity in MPH of the smoke monster
 :param inital_position: Position of the smoke monster
 """
 self.speed = speed
 self.position = initial_position

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

 def fly_to(self, position):
 """
 Have the monster fly to the specified position.

 :param position: Desired location for the monster to fly to.
 """
 if not position.is_valid():
 raise ValueError("Invalid position: " + str(position))
 if not self.can_fly():
 raise RuntimeError("Smoke monster is not currently able to fly.")

 self._fly_to(position)

 def _fly_to(self, position):
 """Equivalent to :meth:`SmokeMonster.fly_to`, but without the safety checks.

 Not normally recommended for end users, but available if you need to
 improve efficiency of the `fly_to` call and you already know it is safe
 to call.
 """
 self.position = position
</code></pre>

Then to document <code>_fly_to</code>, but not <code>_evaporate</code>, you can do:

<pre><code>.. autoclass:: SmokeMonster
 :members:

 .. automethod:: SmokeMonster._fly_to
</code></pre>

blocks|key|1500567|text|这里有一个提示:想象一下private意味着“秘密”。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1500568|这就是为什么Sphinx不会记录它们的原因。|1500569|如果你的意思不是“秘密”，那就考虑更改他们的名字。一般情况下，避免使用单前导下划线名称；除非您有理由对实现保密，否则它不会有任何帮助。|1500570|entityMap^0|0|0|0^^$0|@$1|2|3|4|5|6|7|H|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|I|8|@]|9|@]|A|$]]|$1|D|3|E|5|6|7|J|8|@]|9|@]|A|$]]|$1|F|3|-4|5|6|7|K|8|@]|9|@]|A|$]]]|G|$]]

Here's a hint: imagine that private means "secret". 

That's why Sphinx won't document them. 

If you don't mean "secret", consider changing their names. Avoid using the single-leading-underscore name in general; it doesn't help unless you have a reason to keep the implementation secret.

I am using Sphinx for documenting my python project. I have the autodoc extension enabled and have the following in my docs.

<pre><code>.. autoclass:: ClassName
 :members:
</code></pre>

The problem is, it only documents the non-private methods in the class. How do I include the private methods too?

How can I use Sphinx' Autodoc-extension for private methods?

我使用Sphinx来记录我的python项目。我已经启用了autodoc扩展，并且在我的文档中有以下内容。.. autoclass:: ClassName   :members:问题是，它只记录了类中的非私有方法。如何将私有方法也包含进来？

问如何将Sphinx的Autodoc扩展用于私有方法？
EN

回答 8

Stack Overflow用户

Stack Overflow用户

Stack Overflow用户

社区

活动

资源

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

问如何将Sphinx的Autodoc扩展用于私有方法？EN

回答 8

Stack Overflow用户

Stack Overflow用户

Stack Overflow用户

社区

活动

资源

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

问如何将Sphinx的Autodoc扩展用于私有方法？
EN