在哪里查找文档

在哪里查找文档#

FLAX 文档可在此处找到：https://flax.jax.net.cn/en/latest/

如何构建文档#

使用 git clone https://github.com/google/flax.git 克隆 flax 代码库。
在主 flax 文件夹中，使用 pip install -r docs/requirements.txt 安装所需依赖项。
安装 pandoc：pip install pandoc。
【可选】如果需要对文档进行任何本地更改，请创建并切换到一个分支。在该分支中对文档进行更改。
要构建文档，请在 flax/docs 文件夹中运行 make 脚本：make html。或者，安装 entr，它有助于在文件更改时运行任意命令。然后运行 find ../ ! -regex '.*/[\.|\_].*' | entr -s 'make html'。
如果构建成功，您应该会收到 The HTML pages are in _build/html.（HTML 页面位于 _build/html 中。）的消息。您可以在 flax/docs/_build/html 中预览文档。

如何运行嵌入式代码测试#

我们对文档中的嵌入式代码使用 doctest 块，这些代码也会被测试。在 https://sphinx-doc.cn/en/master/usage/extensions/doctest.html 了解更多信息。

要本地运行测试，请运行 make doctest

如何编写代码文档#

我们的文档是使用 reStructuredText for Sphinx 编写的。它是一种元语言，会被编译成在线文档。有关更多详细信息，请查看 Sphinx 的文档。因此，我们的文档字符串遵循必须牢记的特定语法。下面我们提供一些指南。

要了解如何为 Flax 文档中的 Jupyter Notebooks 或其他格式做出贡献，请参阅专门的贡献页面。

在文档字符串中应包含多少信息#

文档字符串应内容丰富。我们宁愿文档过多也不愿过少。例如，为一个实现新功能的 Module 提供单行解释是不够的。

此外，我们强烈建议在您的文档字符串中添加示例，以便用户可以直接看到代码如何使用。

如何编写内联测试代码#

我们使用 doctest 语法在文档中编写示例。这些示例作为我们 CI 流程的一部分作为测试运行。为了在您的文档中编写 doctest 代码，请使用以下表示法

# Example code::
#
#   def sum(a, b):
#     return a + b
#
#   sum(0, 1)

开头的 Example code 字符串可以替换为任何内容，只要后面有两个冒号和一个换行符，并且代码是缩进的。

如何使用“代码字体”#

在文档字符串中编写代码字体时，请使用双反引号。例如

# This returns a ``str`` object.

请注意，参数名称和诸如 True、None 或任何字符串之类的对象通常应放在 code 中。

如何创建交叉引用/链接#

可以创建指向其他类、函数和方法的交叉引用。在下文中，obj_typ 是 class、func 或 meth。

# First method:
# <obj_type>:`path_to_obj`

# Second method:
# :<obj_type>:`description <path_to_obj>`

如果 path_to_obj 很长，您可以使用第二种方法。一些例子

# Create: a reference to class flax.linen.Module.
# :class:`flax.linen.Module`

# Create a reference to local function my_func.
# :func:`my_func`

# Create a reference "Module.apply()" to method flax.linen.Module.apply.
# :meth:`Module.apply() <flax.linen.Module.apply>`  #

要创建超链接，请使用以下语法

# Note the double underscore at the end:
# `Link to Google <http://www.google.com>`__

如何为类和方法指定参数#

类属性应使用 Attributes: 标签指定。
方法参数应使用 Args: 标签指定。
所有属性和参数都应有类型。

这是我们库中的一个示例

class DenseGeneral(Module):
  """A linear transformation with flexible axes.
    Attributes:
      features: int or tuple with number of output features.
      axis: int or tuple with axes to apply the transformation on. For instance,
        (-2, -1) will apply the transformation to the last two axes.
      batch_dims: tuple with batch axes.
      use_bias: whether to add a bias to the output (default: True).
      dtype: the dtype of the computation (default: float32).
      kernel_init: initializer function for the weight matrix.
      bias_init: initializer function for the bias.
      precision: numerical precision of the computation see `jax.lax.Precision`
        for details.
  """
  features: Union[int, Iterable[int]]
  axis: Union[int, Iterable[int]] = -1
  batch_dims: Iterable[int] = ()
  use_bias: bool = True
  dtype: Dtype = jnp.float32
  kernel_init: Callable[[PRNGKey, Shape, Dtype], Array] = default_kernel_init
  bias_init: Callable[[PRNGKey, Shape, Dtype], Array] = zeros
  precision: Any = None

  @compact
  def __call__(self, inputs: Array) -> Array:
    """Applies a linear transformation to the inputs along multiple dimensions.
    Args:
      inputs: The nd-array to be transformed.
    Returns:
      The transformed input.
    """
    ...