链接到先前的部分：
- 第一部分 -简介，创建代码图形表示所需的图形基元
- 第二部分 -代码生成器的图形表示（主要用Python完成）的实现，微标记语言
- 第三部分 -新的图形功能
下图显示了支持该图形表示的环境示例。
图形代码支持环境本文的第四部分将重点介绍支持文档编制过程。
灌木丛周围
让我们看看在处理文档方面开发人员可以使用的内容。
Python支持模块，类和函数的文档行。 很好 注释有时也用于文档。
有文档生成器，例如
doxygen和
sphinx 。 这也很好。
但是，有时您想要更多。 有时，函数或类的描述过大，文档行（或注释）不必要地“膨胀”。 不可执行的行数开始抑制可执行的行数，由于代码模糊，这会使读取变得困难。 另一个问题是各种图表。 您不能在文本中插入完成的图片。 您只能插入该图的描述，例如
Plant UML图，但是即使在这种情况下，也必须提供渲染，这很难直接在程序文本中进行。
解决问题的方法很简单-将冗长的描述保存在一个单独的文件中，并在代码中留有说明文档。 可以在正确的时间适当地呈现单个文件。 并且代码中的标记最好应该是交互式的，也就是说，只需单击一下鼠标即可提供到文档的过渡。 原则上，可以更广泛地考虑程序文本中的标记：它可以是URL，并且可以位于源文本的另一个文件中的某个位置，图片和带有文档的外部文件中。
很容易想到反向链接。 假设文档中提到了程序源代码中的某个类，甚至提到了特定的代码块。 对于这种情况，最好是快速过渡到所需的代码段。
我们需要考虑另一个重要的情况。 假设在开发过程中需要创建一个外部文档文件。 高度希望组织问题-在何处存储，呼叫什么，如何放置到文档的链接-尽可能自动解决，这样就不会出现不必要的障碍，可以扼杀创建文档的正当冲动。
值得单独讨论的是文档文件格式的问题。 最近，
降价已受到
欢迎 ，尽管对此有所批评（例如，
here ）。 假设github进入项目页面时会自动显示markdown文档，这非常方便。 在这种情况下，您需要遵循非常简单，直观的文件命名和位置协议。 用于markdown的工具也很多，因此这种格式是不错的选择。
在Codimension IDE中的实现
与文本一起，
Codimension IDE支持代码的图形表示。 IDE还支持标记语言。 因此，添加新的图形元素以显示指向文档的链接的任务非常简单。
首先，我们以紧凑的形式提出对新功能的要求：
- 支持带有实时渲染的Markdown格式（查看和编辑）
- 在代码的图形表示中，为使用CML标记语言的文档支持一个新元素
- 文档的图形元素应在三个版本中工作：仅链接到另一个地方； 仅锚定来自其他地方的链接； 并链接和锚定
- 链接可以是URL或指向IDE能够显示的文件（可能带有行号或锚点号）
- 在降价支持中Plant UML图
- 支持快速创建新的文档文件并链接到它们以图形方式显示代码
- 维护项目文档的文档起点，类似于github的工作方式
降价和渲染
Codimension IDE使用
qutepart作为文本编辑器的组件，而qutepart则支持开箱即用的markdown：语法高亮已经完成。 对于自动渲染，可以使用与python文件相同的方法。 主要领域分为两部分。 左边是markdown文本，右边是渲染：
使用自动渲染编辑降价当然，渲染是自动完成的。 IDE定义了文本编辑中的暂停，并在必要时更新渲染。 对于降价视图，隐藏了带有文本编辑器的左侧。
使用
失调库进行
渲染很方便，它使您可以快速将文本转换为HTML。 准备就绪的HTML发送到QT组件进行显示。 失调库还被证明足够灵活，可以为plantUML图描述添加识别功能。 将该图添加为具有相应语言的代码块，例如：
PlantUML图识别plantUML支持各种类型的图。 对于
Codimension，该图
的描述是透明的，也就是说，不对其进行分析，但是plantUML照原样发送。 因此，所有受支持的类型将显示在视口中。 在撰写本文时，plantUML支持各种类型的图的以下开始/结束标签：
- @startuml / @enduml
- @startgantt / @endgantt
- @startsalt / @endsalt
- @startmindmap / @endmindmap
- @startwbs / @endwbs
- @startditaa / @endditaa
- @startjcckit / @endjcckit
可编辑的降价文件可能包含多个图表以及从网络下载的图片。 经常出现的情况是很少的文本更改，而图形资源保持不变。 为了不每次都抽出相同的内容并且不重新生成图，有必要实现类似资源的缓存。
在QT库中，使用了支持HTML的QTextBrowser组件。 不幸的是，HTML支持的方言是有限的，因此最终结果几乎不可能完美。 也许可以在将来修复此缺陷。
鼠标单击链接的过程也需要干预。 以下某些内容可能会出现在链接中：
- 外部资源（以http：//或https：//开头）
- 具有从项目根目录或当前文件开始的相对路径的文件（在文件系统中移动项目目录时方便）
- 文件c的绝对路径
如果是文件，则可以指定（可选元素）此文件中锚点的标识符或行号。 在这两种情况下，都将使用附加信息将文件滚动到所需位置。
图形元素
使用新的CML注释输入图形元素很有意义，类似于已经完成的操作（例如，对于组）。 CML支持属性，新图形元素也需要该属性。
在某些方面，指向文档的链接类似于注释-它不是程序的可执行行，但提供了有关某些上下文的其他信息。
Codimension IDE可以识别几种类型的注释：独立注释，前导注释和横向注释。 对于文档而言，以与注释相同的方式维护独立且领先的图形元素似乎是明智的。 与文档的侧边元素混淆。 关键是如何为多行代码块呈现旁注。 在该块的右侧绘制了一个矩形，覆盖了注释的所有行，并支持匹配的行号。 如果CML文档在旁注中间遇到，该怎么办尚不完全清楚。 另一方面，该链接仍然指向其他地方，因此对CML文档的支持似乎是多余的-代码块中特定行的上下文非常狭窄。 对功能和类的CML文档的支持似乎也很多余。 因此，在此阶段仅将实施独立且领先的CML文档。 值得注意的是，如果将来有合理的需要支持横向CML文档以及如何显示它们的好主意，那么可以添加此功能。
让我们讨论需要在图形元素中显示的内容。 显然，您需要为元素添加文本。 文本由开发人员设置，并告诉您链接指向的内容。 前面提到过，希望通过单击即可提供到文档的过渡。 图形元素的文本不合适，因为必须尊重其他元素行为之间的连续性-单击鼠标可以选择图形元素。 但是，解决问题很简单：例如，您可以在文本左侧添加一个图标，然后单击该图标即可进行过渡。
现在，CML doc注释的属性列表已清除：
- 链接-链接到另一个地方
- 锚-来自其他地方的链接的锚标识符
- title-要在图形元素中显示的文本
- bg，fg，border-元素的单独颜色（如果需要以特殊方式突出显示）
必须存在链接和锚点这两个属性中的至少一个。 没有它们，这样的CML文档注释就没有多大意义。 其他属性是可选的。 文本可能根本不是，颜色可能是标准的。
这是使用CML文档及其图形表示形式的代码示例：
独立且领先的CML文档评论引导元素和独立元素之间的区别仅在于连接器的位置：连接到特定块或块之间的连接器。
当鼠标光标悬停在图标上并且元素具有链接属性时，光标的形状将发生变化，这表明将执行单击。
图形元素还支持上下文菜单。 可以使用一个选项来查看或编辑元素属性（包括颜色）以及删除元素的选项。
其他图形元素
代码的图形表示中几乎所有其他元素都可以具有文档（例如，注释和文档字符串除外）。 因此，他们有一种通过上下文菜单创建文档项的方法。
用于处理文档的上下文菜单只有两个选择。 第一个“添加/编辑文档链接/锚点...”将导致一个模式对话框，用于手动输入链接，锚点和标题属性。 在这里，开发人员拥有完全的自由权，可以在哪里发送链接，在哪里放置文件等。
第二种选择更有趣。 由于执行了以下操作，该项目的名称很长：“创建doc文件，添加链接并打开以进行编辑”。 所有操作都是自动执行的，无需任何输入，因此您可以快速解决组织问题：
- 确定文档所在的文件（我们将在下面考虑）
- 在源文本中，添加
# cml 1 doc ... ，它指向文档文件并具有生成的锚点和文本。 锚生成为doc <随机数>。 固定文本：请参阅文档 - 如果文档文件已经存在，它将在新选项卡中打开以进行编辑
- 如果文档文件不存在，则会创建该文件并打开以在新选项卡中进行编辑，并将简短帮助添加到编辑缓冲区，包括如何引用刚刚插入的
# cml 1 doc ...注释。
关于文件的决定取决于是否加载了项目。 如果已加载，则将在项目根目录中创建doc子目录，然后在项目根目录至源文本文件之间创建相对路径。 通过将扩展名替换为.md来形成文件名。 例如，如果一个项目位于
/home/me/myProject
并为项目文件添加了文档
/home/me/myProject/src/utils.py
将创建一个文档文件
/home/me/myProject/doc/src/utils.md
因此，源代码文档的结构重复了源代码的结构，即使快速查看项目中的doc子目录也足以实现直观导航。 对于默认行为，该方案似乎是合理的，这有助于加快文档编制工作。
如果未加载项目，则会在文件旁边创建doc子目录，并在其中创建扩展名为.md的文件。 但是，这种情况似乎不太可能。 如果我们在谈论文档，那几乎可以肯定是项目的工作，而不是单独的文件。
当然，您随时可以通过在文本编辑器中或在图形表示形式的对话框中编辑
# cml 1 doc ...来更改自动生成的元素。
项目文档起点
为什么需要文档起点？ 我认为，它可以为首次打开该项目的人员提供便利，以使其进入该项目。 例如，在扩大开发团队组成或针对项目用户的情况下。 想象一下该项目有文档，并且由大量文件组成。 从哪里开始？ 文件的结构如何？ 与其推测然后检查它们，不如对建议的入口点有明确的指示。
在这里，您可以扩展github方法，以便默认选项和特定文档组织选项都可以使用。 如果什么也没说，那么我们将在项目根目录中查找README.md文件。 并且可以使用另一个字段来扩展项目的属性，该字段指示文档起点的特定文件。
有两个打开项目文档的选项。 具有降价图标的按钮已添加到IDE主窗口的工具栏中。 单击后，文档文件将以查看模式打开（如果可用）。 如果没有文件，则将提供文档文件的位置，并且将在编辑模式下打开一个新标签，其中包含文本-存根。 第二个选项是指向
Codimension欢迎页面的链接，该页面在没有其他打开的选项卡时显示。 随附的文本将包括有关项目文档的文字以及如果找到文档的链接。 首次打开该项目的用户将看到此欢迎页面。
实际测试
上面描述的功能已在cats（即
Codimension IDE本身的项目）上进行了
测试 。 现在，安装包中包含以降价格式准备的文档。 此功能测试不能认为是完全完成的，因为文档是为最终用户准备的，而不是为代码准备的。 但是，事实证明总体上还是可以接受的。
公开问题
我是否需要对CML文档辅助元素的支持？ 如果是，那么例如在这种情况下如何绘制它们：
a = 10
可以直接在文档行中识别plantUML图描述。 如果提供了这种支持，那么如何在代码的图形表示中显示这些图呢？
为了促进plantUML图的构建，可以在这种情况下添加功能：
- 用户在代码的图形表示形式或任何其他窗口（项目类列表，结构化文件内容）中右键单击该类。
- 在上下文菜单中，选择一个项目以生成plantUML格式的类描述
- 生成的描述将保存在文本缓冲区中。
- 用户将文本插入降价文档，并在必要时进行修改
这种方案的生命力值得怀疑，尽管实施起来并不容易。
如果您有任何想法，请在评论中分享。