Skip to content

飞桨文档相互引用

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