Skip to content

飞桨文档相互引用

Jump to bottom
Nyakku Shigure edited this page Aug 30, 2023 · 9 revisions

背景

某同学在撰写文档A，希望引用另一篇文档B中的内容，两篇之间如果能够互相跳转，则更方便用户的理解

文档的结构体系常常发生变化，如果把超链接写死，不仅不利于文档的维护，也容易让用户踩坑

那么，如何让A、B文档直接灵活地引用彼此呢？

指南

首先确认下自己要改的是英文还是中文文档，规则是英文跳英文、中文跳中文，确认自己写的A文档和要跳转的B文档是什么格式，你通常会遇到以下三种情况：

1）A文档和B文档均为rst格式，飞桨的API文档通常采用这种格式，可以使用一种非常简单并且维护成本低的跳转方法；

2）A文档为rst格式，B文档为非rst格式，例如md格式，需要使用rst的超链接引用格式；

3）A文档为md格式，需要使用md的超链接引用格式。

我们分情况来介绍引用方式和示例。

情况一：A文档和B文档均为rst格式

我们以B文档是 paddle.add 为例，点击raw，查看文档的源代码，在文档第一行发现

.. _cn_api_tensor_add:

这个就是B文档的“标签”了，我们在A文档里用

:ref:`cn_api_tensor_add`

这种语法（仔细观察，发现去掉了多余的点、冒号和前面的下划线）去写，被官网渲染后就可以直接在A文档里生成一个B文档的链接

请注意

:ref:`cn_api_tensor_add`

的前后一定要分别留一个空格，否则，在官网上会显示出奇怪的效果

而如果你需要引用的 B 文档是英文文档，那么标签通常是自动生成的，你可以通过如下方式计算需要引用的 B 文档正确的标签。

"api_" + api_name.replace(".", "_")

比如对于 paddle.add，如果需要引用该 API 的英文文档，你只需要使用：

:ref:`api_paddle_add`

情况二：A文档为rst格式，B文档为非rst格式

我们以B文档是 Broadcasting of Tensor 为例，需要使用rst的超链接引用格式，即：

# 方法一：
# `链接文字 <URL>`_
`Broadcasting of Tensor <https://www.paddlepaddle.org.cn/documentation/docs/en/develop/guides/beginner/tensor_en.html#chapter5-broadcasting-of-tensor>`_

# 方法二：
# `链接文字`_
# .. _链接文字: URL
please refer to `Introduction to Tensor`_ .
    .. _Introduction to Tensor: ../../guides/beginner/tensor_en.html#chapter5-broadcasting-of-tensor

请注意末尾的下划线一定要保留，否则超链接无法正常生成。 建议同站URL使用相对路径，外站URL使用绝对路径。

情况三：A文档为md格式

直接采用大家熟悉的md超链接引用格式即可。

# [链接文字](URL)
[飞桨API文档目录](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/index_cn.html)

FAQ

  1. 为什么不建议用绝对路径？
  • 因为官网的文档是随版本升级动态更新的，绝对路径中会包含版本信息（或默认为最新版本），上个版本可以正确跳转的文档，下个版本存在一定概率会跪。相对路径可以保证文档链接随版本变更，避免用户遇到死链。
  1. 为什么强烈推荐用rst？
  • 官网组织文档的框架sphinx原生支持rst，而且rst好处多多，初次学习有一定门槛，之后就会方便很多；另外源码的注释也是用rst格式来写的，大家或多或少会接触到，越早学习没有坏处~
  1. 如果我还是不知道写法，怎么办？
  • 可以去Github docs Repo中看一下，当前有很多文档中都用了这种引用，你也可以参考这个 PR46347
Clone this wiki locally