uTools-Manuals/docs/python/pydoc.html

<div class="body" role="main"><div class="section" id="module-pydoc"><h1><span class="yiyi-st" id="yiyi-10">26.2. <a class="reference internal" href="#module-pydoc" title="pydoc: Documentation generator and online help system."><code class="xref py py-mod docutils literal"><span class="pre">pydoc</span></code></a>  - 文档生成器和在线帮助系统</span></h1><p><span class="yiyi-st" id="yiyi-11"><strong>源代码：</strong> <a class="reference external" href="https://hg.python.org/cpython/file/3.5/Lib/pydoc.py">Lib / pydoc.py</a></span></p><p><span class="yiyi-st" id="yiyi-12"><a class="reference internal" href="#module-pydoc" title="pydoc: Documentation generator and online help system."><code class="xref py py-mod docutils literal"><span class="pre">pydoc</span></code></a>模块会自动从Python模块生成文档。</span><span class="yiyi-st" id="yiyi-13">文档可以作为文本页面显示在控制台上，提供给Web浏览器或保存到HTML文件。</span></p><p><span class="yiyi-st" id="yiyi-14">对于模块，类，函数和方法，显示的文档是从docstring（即。</span><span class="yiyi-st" id="yiyi-15">对象的<code class="xref py py-attr docutils literal"><span class="pre">__doc__</span></code>属性），以及其可记录成员的递归。</span><span class="yiyi-st" id="yiyi-16">如果没有docstring，<a class="reference internal" href="#module-pydoc" title="pydoc: Documentation generator and online help system."><code class="xref py py-mod docutils literal"><span class="pre">pydoc</span></code></a>会尝试从源文件中的类，函数或方法的定义上方或模块顶部的注释行块获取描述（参见<a class="reference internal" href="inspect.html#inspect.getcomments" title="inspect.getcomments"><code class="xref py py-func docutils literal"><span class="pre">inspect.getcomments()</span></code></a>）。</span></p><p><span class="yiyi-st" id="yiyi-17">内建函数<a class="reference internal" href="functions.html#help" title="help"><code class="xref py py-func docutils literal"><span class="pre">help()</span></code></a>调用交互式解释器中的联机帮助系统，它使用<a class="reference internal" href="#module-pydoc" title="pydoc: Documentation generator and online help system."><code class="xref py py-mod docutils literal"><span class="pre">pydoc</span></code></a>在控制台上生成文本文本。</span><span class="yiyi-st" id="yiyi-18">通过在操作系统的命令提示符下将<strong class="program">pydoc</strong>作为脚本运行，也可以从Python解释器外部查看相同的文本文档。</span><span class="yiyi-st" id="yiyi-19">例如，运行</span></p><pre><code class="language-python"><span></span><span class="n">pydoc</span> <span class="n">sys</span>
</code></pre><p><span class="yiyi-st" id="yiyi-20">在shell提示符下，将以类似于由Unix <strong class="program">man</strong>命令显示的手册页的样式显示<a class="reference internal" href="sys.html#module-sys" title="sys: Access system-specific parameters and functions."><code class="xref py py-mod docutils literal"><span class="pre">sys</span></code></a>模块上的文档。</span><span class="yiyi-st" id="yiyi-21"><strong class="program">pydoc</strong>的参数可以是函数，模块或程序包的名称，也可以是程序包中模块或模块中类，方法或函数的虚线引用。</span><span class="yiyi-st" id="yiyi-22">如果<strong class="program">pydoc</strong>的参数看起来像一个路径（即，它包含操作系统的路径分隔符，例如Unix中的斜杠），并引用现有的Python源文件，则文档为该文件生成。</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-23">注意</span></p><p class="last"><span class="yiyi-st" id="yiyi-24">为了找到对象及其文档，<a class="reference internal" href="#module-pydoc" title="pydoc: Documentation generator and online help system."><code class="xref py py-mod docutils literal"><span class="pre">pydoc</span></code></a>导入要记录的模块。</span><span class="yiyi-st" id="yiyi-25">因此，模块级别上的任何代码都将在此时执行。</span><span class="yiyi-st" id="yiyi-26">使用<code class="docutils literal"><span class="pre">if</span> <span class="pre">__ name __</span> <span class="pre">==</span> <span class="pre">'__ main __'：</span></code>当一个文件作为脚本调用，而不是只是导入。</span></p></div><p><span class="yiyi-st" id="yiyi-27">当打印输出到控制台时，<strong class="program">pydoc</strong>尝试对输出进行分页以便于阅读。</span><span class="yiyi-st" id="yiyi-28">If the <span class="target" id="index-1"></span><code class="xref std std-envvar docutils literal"><span class="pre">PAGER</span></code> environment variable is set, <strong class="program">pydoc</strong> will use its value as a pagination program.</span></p><p><span class="yiyi-st" id="yiyi-29">在参数前指定<code class="docutils literal"><span class="pre">-w</span></code>标志将导致HTML文档写入当前目录中的文件，而不是在控制台上显示文本。</span></p><p><span class="yiyi-st" id="yiyi-30">在参数之前指定<code class="docutils literal"><span class="pre">-k</span></code>标志，将以类似于Unix <strong class="program">man</strong>命令的方式，搜索作为参数给出的关键字的所有可用模块的摘要行。</span><span class="yiyi-st" id="yiyi-31">模块的概要行是其文档字符串的第一行。</span></p><p><span class="yiyi-st" id="yiyi-32">您还可以使用<strong class="program">pydoc</strong>在本地计算机上启动HTTP服务器，该服务器将提供文档以访问Web浏览器。</span><span class="yiyi-st" id="yiyi-33"><strong class="program">pydoc -p 1234</strong>将在端口1234上启动HTTP服务器，允许您在首选的Web浏览器中浏览<code class="docutils literal"><span class="pre">http://localhost:1234/</span></code>上的文档。</span><span class="yiyi-st" id="yiyi-34">指定<code class="docutils literal"><span class="pre">0</span></code>作为端口号将选择任意未使用的端口。</span></p><p><span class="yiyi-st" id="yiyi-35"><strong class="program">pydoc -b</strong>将启动服务器，并另外打开Web浏览器到模块索引页面。</span><span class="yiyi-st" id="yiyi-36">Each served page has a navigation bar at the top where you can <em>Get</em> help on an individual item, <em>Search</em> all modules with a keyword in their synopsis line, and go to the <em>Module index</em>, <em>Topics</em> and <em>Keywords</em> pages.</span></p><p><span class="yiyi-st" id="yiyi-37">当<strong class="program">pydoc</strong>生成文档时，它使用当前环境和路径来定位模块。</span><span class="yiyi-st" id="yiyi-38">因此，如果您启动Python解释器并输入<code class="docutils literal"><span class="pre">import</span> <span class="pre">垃圾邮件</span>，则调用<strong class="program">pydoc spam</strong> </code>。</span></p><p><span class="yiyi-st" id="yiyi-39">核心模块的模块文档假定位于<code class="docutils literal"><span class="pre">https://docs.python.org/X.Y/library/</span></code>中，其中<code class="docutils literal"><span class="pre">X</span></code>和<code class="docutils literal"><span class="pre">Y</span></code>是Python解释器的主要版本号和次要版本号。</span><span class="yiyi-st" id="yiyi-40">可以通过将<span class="target" id="index-2"></span> <code class="xref std std-envvar docutils literal"><span class="pre">PYTHONDOCS</span></code>环境变量设置为其他URL或包含库参考手册页的本地目录来覆盖此操作。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-41"><span class="versionmodified">在版本3.2中已更改：</span>添加了<code class="docutils literal"><span class="pre">-b</span></code>选项。</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-42"><span class="versionmodified">在版本3.3中已更改：</span>已删除<code class="docutils literal"><span class="pre">-g</span></code>命令行选项。</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-43"><span class="versionmodified">在版本3.4中更改：</span> <a class="reference internal" href="#module-pydoc" title="pydoc: Documentation generator and online help system."><code class="xref py py-mod docutils literal"><span class="pre">pydoc</span></code></a>现在使用<a class="reference internal" href="inspect.html#inspect.signature" title="inspect.signature"><code class="xref py py-func docutils literal"><span class="pre">inspect.signature()</span></code></a>而不是<a class="reference internal" href="inspect.html#inspect.getfullargspec" title="inspect.getfullargspec"><code class="xref py py-func docutils literal"><span class="pre">inspect.getfullargspec()</span></code></a></span></p></div></div></div>