Skip to content

飞桨文档相互引用

Jump to bottom
Chen Long edited this page Mar 30, 2021 · 9 revisions

背景

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

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

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

指南

首先确认下自己要改的是英文还是中文文档 规则是英文跳英文、中文跳中文 找找自己写的A文档和要跳转的B文档是什么格式 1） 在Github FluidDoc Repo里找到自己想跳的那篇文档，如： paddle.add

2） 文档一般为rst或md格式。 如果A和B都是rst，恭喜可以使用一种非常简单并且维护成本低的跳转方法： 点击raw，查看文档的源代码，在文档第一行发现

.. _cn_api_tensor_add:

这个就是B文档的“标签”了，我们在A文档里用 :ref:cn_api_tensor_add 这种语法（仔细观察，发现去掉了多余的点、冒号和前面的下划线）去写，被官网渲染后就可以直接在A文档里生成一个B文档的链接 请注意:ref:cn_api_tensor_add的前后一定要分别留一个空格，否则，在官网上会显示出奇怪的效果

如果A和B有一篇是md文档（如果只有A是md，强烈建议改用rst去写，维护起来非常方便），那么很遗憾当前只能写相对路径： 具体怎样相对，要视A文档和B文档在Github上的路径而定，例如../xxx.html（注意！无论B文档实际是什么格式，它被用相对路径引用时，后缀必须是html，否则到了官网会有奇怪的效果） 于是就完成了。

FAQ

  1. 为什么不建议用相对路径？ 因为官网的文档结果每次发版都有可能变，上个版本可以正确跳转的文档，下个版本存在一定概率会跪。重点是在调整文档结构的时候，你无法知道有多少篇其他文档用相对链接引用了这篇文档，这样的维护成本会指数级上升，现有人力无法及时去修复，用户会遇到死链。
  2. 为什么强烈推荐用rst？ 官网组织文档的框架sphinx原生支持rst，而且rst好处多多，初次学习有一定门槛，之后就会方便很多；另外源码的注释也是用rst格式来写的，大家或多或少会接触到，越早学习没有坏处~
  3. 如果我还是不知道写法，怎么办？ 可以去Github FluidDoc Repo中看一下，当前有很多文档中都用了这种引用，例如可看下下每个API文档目录之下的Overview，有很多到API接口文档的跳转： paddle.Overview
Clone this wiki locally