只要在当前文档中提供了链接就可以通过以两个点开头的特殊行将文本更改外部链接如下所示Try ‘Plone CMS’, it is great ! It is based on Zope.… _‘Plone CMS’: http://plone.org… _Zope: http://zope.org通常的做法是将外部链接分组放到文档的末尾。当要链接的文本包含空格时它必须用反引号字符包围。也可以通过在文本中添加标记来使用内部链接如下所示This is a code example… _example:::1 12Let’s continue our text, or maybe go back tothe example_.章节也可以使用内部链接如下所示Document titleIntroduction to the document content.Section 1First document section.Section 2- go back to ‘Section 1’_构建文档指导读者和作者的一个更简单的方法是向每个人提供帮助和指导正如我们在本章前面的章节中所学到的。从作者的角度来看这可以通过一组可重用的模板以及描述如何以及何时在项目中使用它们的指南来完成。它被称为文档集documentation portfolio。从读者的角度来看重要的是能够无痛地浏览文档并习惯于有效地查找信息。它是通过构建文档格局document landscape来完成的。构建文档集软件项目可以有许多种类的文档从直接引用代码的底层文档到提供应用程序的高层次视图的设计文档。例如Scott Ambler 在他的书 Agile Modeling: Effective Practices for eXtreme Programmingand the Unified Process 中定义了广泛的文档类型列表。他从早期规范到操作文档构建了一个文档集。甚至包括项目管理文档因此整个文档需求都是使用一组标准化的模板构建。由于完整的文档集与用于构建软件的方法密切相关本章将仅关注你可以根据特定需求完成的公共子集。构建高效的文档集需要很长时间因为它可以体现你的工作习惯。软件项目中的一组常见文档可以分为 3 类。● 设计包括提供架构信息和底层设计信息的所有文档例如类图或数据库图。● 用法包括有关如何使用软件的所有文档;可以是以一本手册和教程或模块级帮助的形式。● 操作这提供了有关如何部署升级或操作软件的指南。设计创建此类文档的重点是确保目标读者是完全知道的内容范围有限的。因此为作者提供一点建议就是设计文档的通用模板尽量保持轻量级的结构。这样的结构可能包括● 标题● 作者● 标签关键字● 说明摘要● 目标谁应该读这篇文章● 内容带图● 参考的其他文件。打印时内容最多应为 3 页或 4 页以确保限制范围。如果它变大应该分成几个文档或概述。该模板还提供了作者的名字和一个标签列表来管理它的演变和简化分类。这将在本章后面讨论。reST 中的示例设计文档模板如下所示Design document title:Author: Document Author:Tags: document tags separated with spaces:abstract:Write here a small abstract about your design document.… contents ::AudienceExplain here who is the target readership.ContentWrite your document here. Do not hesitate to split it in severalsections.ReferencesPut here references, and links to other documents.使用使用文档描述软件的特定部分是如何使用的。本文档可以描述底层部分如函数的工作原理也可以描述高层部分如调用程序的命令行参数。这是框架应用程序中的文档的最重要的部分因为目标读者主要是将要重用代码的开发人员。3 种主要的文件如下。● 技巧这是一个简短的文档解释如何做某事。这种文件瞄准一个读者并专注于一个特定的主题。● 教程这是一个逐步的文档说明如何使用软件的功能。本文档可以引用配方文档每个实例仅供一个读者使用。● 模块助手这是一个底层文档用于说明模块包含的内容。当你通过模块调用内置的帮助时可以显示此文档。技巧一个技巧recipe文档解答一个非常具体的问题并提供一个解决方案来解决问题。例如ActiveState 在线提供了一个庞大 Python 配方仓库开发人员可以在其中描述如何使用 Python 做事情参考 http://code.activestate.com/recipes/langs/python/。与单个区域/项目相关的这样一组配方通常被称为攻略cookbook。这些技巧必须简短并且结构如下。● 标题。● 提交者。● 最近更新时间。● 版本。● 类别。● 说明。● 源源代码。● 讨论解释代码的文字。● 评论来自网络。通常它们很长超出一屏但是却没有深入细节。这种结构完全符合软件的需要可以在通用结构中再进行调整向其中添加目标读者并且用标签替换类别● 标题短句。● 作者。● 标签关键字。● 谁应该读这个● 先决条件例如要读取的其他文档。● 问题简短说明。● 解决方案主文本一个或两个屏幕。● 参考文献指向其他文档的链接。上面没有日期和版本因为像管理项目中的源代码一样管理项目文档。这意味着处理文档的最好方法是通过版本控制系统进行管理。在大多数情况下这与用于项目代码的代码仓库完全相同。一个简单的可重用的配方模板如下Recipe name:Author: Recipe Author:Tags: document tags separated with spaces:abstract:Write here a small abstract about your design document.… contents ::AudienceExplain here who is the target readership.PrerequisitesWrite the list of prerequisites for implementing this recipe. Thiscan be additional documents, software, specific libraries, environmentsettings or just anything that is required beyond the obvious languageinterpreter.ProblemExplain the problem that this recipe is trying to solve.SolutionGive solution to problem explained earlier. This is the core of arecipe.ReferencesPut here references, and links to other documents.教程教程和配方相比有着不同的目的。它不打算解决孤立的问题而是描述如何逐步使用应用程序的功能。这可能比配方更长并且可能涉及应用程序的许多部分。例如Django 在其网站上提供了一个教程列表。Writing your first Django App, part1参考 https://docs.djangoproject.com/en/1.9/intro/tutorial01/解释如何使用 Django 构建应用程序。这种文件的结构如下所示。● 标题短句。● 作者。● 标签文字。● 说明摘要。● 谁应该读这个● 先决条件例如要读取的其他文档。● 教程正文。● 参考文献指向其他文档的链接。模块助手模块助手模板是可以添加到我们的集合中的最后一个模板。模块助手指的是一个单独的模块它主要提供内容的描述以及使用示例。一些工具可以通过使用 pydoc 提取 docstrings 和计算模块助手来自动构建这样的文档例如 Epydoc参考 http://epydoc.sourceforge.net。因此可以基于内省 API 生成大量的文档。通常在 Python 框架中会提供这种文档。例如Plone 提供了一个 http://api.plone.org 服务器以保持模块助手的最新集合。这种方法的主要问题如下。● 无法智能的选择感兴趣的模块生成文档。● 代码可能会被文档混淆。此外模块文档提供的例子有时可能涉及模块的多个部分并且它们很难在函数和类的 docstrings 之间进行拆分。模块的 docstring 的目的是可以在模块的顶部写入文本。但是这最终得到一个由一个文本块组成的混合文件而不是一个代码块。当代码小于总长度的 50%时这是相当模糊的。如果你是作者这当然没问题。但是当人们尝试读取代码而不是文档时他们将不得不跳过 docstrings 部分。另一种方法是将这些文本拆分到单独的文件中。然后通过手动的操作决定哪个 Python模块具有模块助手文件。然后文档可以从代码库中分离出来并允许它们独立生存我们将在下一部分中看到。Python 的文档就是这样处理的。事实上许多开发人员不认同文档和代码分离比 docstrings 更好。这种方案法意味着文档编写过程要完全纳入到开发周期中否则文档就会很快过时。docstrings 方案通过让代码及其用法示例之间的保持来解决这个问题但是不能将其带到更高级别——一个可以用作纯文本文件一部分的文档。模块助手的模板非常简单因为它在内容写入之前只包含一些元数据。目标读者没有定义直到有希望使用此模块的开发人员。● 标题模块名称。● 作者。● 标签文字。● 内容。操作操作文档用于描述如何操作软件需要考虑以下几点。● 安装和部署文档。● 管理文件。● 常见问题FAQ文档。● 解释人们如何贡献请求帮助或提供反馈的文档。这些文档非常具体但他们可以使用前面部分中定义的教程模板。
Python 高手编程系列三千三百七十七：链接
只要在当前文档中提供了链接就可以通过以两个点开头的特殊行将文本更改外部链接如下所示Try ‘Plone CMS’, it is great ! It is based on Zope.… _‘Plone CMS’: http://plone.org… _Zope: http://zope.org通常的做法是将外部链接分组放到文档的末尾。当要链接的文本包含空格时它必须用反引号字符包围。也可以通过在文本中添加标记来使用内部链接如下所示This is a code example… _example:::1 12Let’s continue our text, or maybe go back tothe example_.章节也可以使用内部链接如下所示Document titleIntroduction to the document content.Section 1First document section.Section 2- go back to ‘Section 1’_构建文档指导读者和作者的一个更简单的方法是向每个人提供帮助和指导正如我们在本章前面的章节中所学到的。从作者的角度来看这可以通过一组可重用的模板以及描述如何以及何时在项目中使用它们的指南来完成。它被称为文档集documentation portfolio。从读者的角度来看重要的是能够无痛地浏览文档并习惯于有效地查找信息。它是通过构建文档格局document landscape来完成的。构建文档集软件项目可以有许多种类的文档从直接引用代码的底层文档到提供应用程序的高层次视图的设计文档。例如Scott Ambler 在他的书 Agile Modeling: Effective Practices for eXtreme Programmingand the Unified Process 中定义了广泛的文档类型列表。他从早期规范到操作文档构建了一个文档集。甚至包括项目管理文档因此整个文档需求都是使用一组标准化的模板构建。由于完整的文档集与用于构建软件的方法密切相关本章将仅关注你可以根据特定需求完成的公共子集。构建高效的文档集需要很长时间因为它可以体现你的工作习惯。软件项目中的一组常见文档可以分为 3 类。● 设计包括提供架构信息和底层设计信息的所有文档例如类图或数据库图。● 用法包括有关如何使用软件的所有文档;可以是以一本手册和教程或模块级帮助的形式。● 操作这提供了有关如何部署升级或操作软件的指南。设计创建此类文档的重点是确保目标读者是完全知道的内容范围有限的。因此为作者提供一点建议就是设计文档的通用模板尽量保持轻量级的结构。这样的结构可能包括● 标题● 作者● 标签关键字● 说明摘要● 目标谁应该读这篇文章● 内容带图● 参考的其他文件。打印时内容最多应为 3 页或 4 页以确保限制范围。如果它变大应该分成几个文档或概述。该模板还提供了作者的名字和一个标签列表来管理它的演变和简化分类。这将在本章后面讨论。reST 中的示例设计文档模板如下所示Design document title:Author: Document Author:Tags: document tags separated with spaces:abstract:Write here a small abstract about your design document.… contents ::AudienceExplain here who is the target readership.ContentWrite your document here. Do not hesitate to split it in severalsections.ReferencesPut here references, and links to other documents.使用使用文档描述软件的特定部分是如何使用的。本文档可以描述底层部分如函数的工作原理也可以描述高层部分如调用程序的命令行参数。这是框架应用程序中的文档的最重要的部分因为目标读者主要是将要重用代码的开发人员。3 种主要的文件如下。● 技巧这是一个简短的文档解释如何做某事。这种文件瞄准一个读者并专注于一个特定的主题。● 教程这是一个逐步的文档说明如何使用软件的功能。本文档可以引用配方文档每个实例仅供一个读者使用。● 模块助手这是一个底层文档用于说明模块包含的内容。当你通过模块调用内置的帮助时可以显示此文档。技巧一个技巧recipe文档解答一个非常具体的问题并提供一个解决方案来解决问题。例如ActiveState 在线提供了一个庞大 Python 配方仓库开发人员可以在其中描述如何使用 Python 做事情参考 http://code.activestate.com/recipes/langs/python/。与单个区域/项目相关的这样一组配方通常被称为攻略cookbook。这些技巧必须简短并且结构如下。● 标题。● 提交者。● 最近更新时间。● 版本。● 类别。● 说明。● 源源代码。● 讨论解释代码的文字。● 评论来自网络。通常它们很长超出一屏但是却没有深入细节。这种结构完全符合软件的需要可以在通用结构中再进行调整向其中添加目标读者并且用标签替换类别● 标题短句。● 作者。● 标签关键字。● 谁应该读这个● 先决条件例如要读取的其他文档。● 问题简短说明。● 解决方案主文本一个或两个屏幕。● 参考文献指向其他文档的链接。上面没有日期和版本因为像管理项目中的源代码一样管理项目文档。这意味着处理文档的最好方法是通过版本控制系统进行管理。在大多数情况下这与用于项目代码的代码仓库完全相同。一个简单的可重用的配方模板如下Recipe name:Author: Recipe Author:Tags: document tags separated with spaces:abstract:Write here a small abstract about your design document.… contents ::AudienceExplain here who is the target readership.PrerequisitesWrite the list of prerequisites for implementing this recipe. Thiscan be additional documents, software, specific libraries, environmentsettings or just anything that is required beyond the obvious languageinterpreter.ProblemExplain the problem that this recipe is trying to solve.SolutionGive solution to problem explained earlier. This is the core of arecipe.ReferencesPut here references, and links to other documents.教程教程和配方相比有着不同的目的。它不打算解决孤立的问题而是描述如何逐步使用应用程序的功能。这可能比配方更长并且可能涉及应用程序的许多部分。例如Django 在其网站上提供了一个教程列表。Writing your first Django App, part1参考 https://docs.djangoproject.com/en/1.9/intro/tutorial01/解释如何使用 Django 构建应用程序。这种文件的结构如下所示。● 标题短句。● 作者。● 标签文字。● 说明摘要。● 谁应该读这个● 先决条件例如要读取的其他文档。● 教程正文。● 参考文献指向其他文档的链接。模块助手模块助手模板是可以添加到我们的集合中的最后一个模板。模块助手指的是一个单独的模块它主要提供内容的描述以及使用示例。一些工具可以通过使用 pydoc 提取 docstrings 和计算模块助手来自动构建这样的文档例如 Epydoc参考 http://epydoc.sourceforge.net。因此可以基于内省 API 生成大量的文档。通常在 Python 框架中会提供这种文档。例如Plone 提供了一个 http://api.plone.org 服务器以保持模块助手的最新集合。这种方法的主要问题如下。● 无法智能的选择感兴趣的模块生成文档。● 代码可能会被文档混淆。此外模块文档提供的例子有时可能涉及模块的多个部分并且它们很难在函数和类的 docstrings 之间进行拆分。模块的 docstring 的目的是可以在模块的顶部写入文本。但是这最终得到一个由一个文本块组成的混合文件而不是一个代码块。当代码小于总长度的 50%时这是相当模糊的。如果你是作者这当然没问题。但是当人们尝试读取代码而不是文档时他们将不得不跳过 docstrings 部分。另一种方法是将这些文本拆分到单独的文件中。然后通过手动的操作决定哪个 Python模块具有模块助手文件。然后文档可以从代码库中分离出来并允许它们独立生存我们将在下一部分中看到。Python 的文档就是这样处理的。事实上许多开发人员不认同文档和代码分离比 docstrings 更好。这种方案法意味着文档编写过程要完全纳入到开发周期中否则文档就会很快过时。docstrings 方案通过让代码及其用法示例之间的保持来解决这个问题但是不能将其带到更高级别——一个可以用作纯文本文件一部分的文档。模块助手的模板非常简单因为它在内容写入之前只包含一些元数据。目标读者没有定义直到有希望使用此模块的开发人员。● 标题模块名称。● 作者。● 标签文字。● 内容。操作操作文档用于描述如何操作软件需要考虑以下几点。● 安装和部署文档。● 管理文件。● 常见问题FAQ文档。● 解释人们如何贡献请求帮助或提供反馈的文档。这些文档非常具体但他们可以使用前面部分中定义的教程模板。
