我目前正在学习 Python 文档字符串,特别是在 Google 风格、NumPy 风格和 Sphinx 风格格式的背景下。 我注意到有时这些文档字符串的行首有两个点,我很想了解它们的意义和用法。 这些是什么意思以及如何使用?
此外,我还遇到过一些情况,有些行有两个冒号(例如,.. math::),而其他行则有只有一个(例如,.._label-text:)。如果有人可以解释其中的差异并就何时使用其中一种提供指导,我将不胜感激。
作为参考,以下是来自不同来源的一些示例,展示了这些模式:
.. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
.. image:: filename
.. [1] O. McNoleg, "The integration of GIS, remote sensing,
expert systems and adaptive co-kriging for environmental habitat
modelling of the Highland Haggis using object-oriented, fuzzy-logic
and neural-network techniques," Computers & Geosciences, vol. 22,
pp. 585-588, 1996.
.. _label-text:
Example title
-------------
.. directive-name:: arg1 arg2 arg3
:named-parameter1: value1
:named-parameter2: value2
Text that the directive should be applied to. it
must be indented. also note the blank link before
the text starts.
The text block can span multiple paragraphs, and
ends when indentation returns to its previous level.
.. note::
Directives can be nested like this. Notice the
simpler syntax for directives that do not
require any arguments.
.. _Google Python Style Guide:
http://google.github.io/styleguide/pyguide.html
我在google上搜索了很多网站,但没有得到很好的答案。 我希望有人能帮助我理解这些是什么以及如何使用?
直接来自 Sphinx 文档 (https://python-tooling-example.readthedocs.io/en/latest/docs.html)
两个点、一个空格和一个下划线标记标签的开始。冒号标志着结束。:
.. _label-text:
Example title
使用指令的语法类似于标签。两个点和空格标记指令的开头(注意没有下划线!),两个冒号划分指令名称的结尾:
.. directive-name:: arg1 arg2 arg3
:named-parameter1: value1
:named-parameter2: value2
Text that the directive should be applied to. it
must be indented. also note the blank link before
the text starts.
The text block can span multiple paragraphs, and
ends when indentation returns to its previous level.
.. note::
Directives can be nested like this. Notice the
simpler syntax for directives that do not
require any arguments.
因此,用外行人的话来说,这似乎是在文档字符串布局中创建结构的一种方法。感觉有点像乳胶。