Configuration

Project information

sophon.yml must contain following information.

code_dir

指定您Python项目所在的文件夹。

Sophon会将该目录插入到sys.path中，以让Python解析器能够import。
code_dir支持相对路径。如果是相对路径则是相对于sophon.yml而言。
可以不指定code_dir，默认为.。

template_dir

存放Markdown模板的文件夹。模板文件就是Markdown文件，只不还包含了一些形如{{tag_name}}的标记。更多详细用法请看tags。

template_dir支持相对路径。如果是相对路径则是相对于sophon.yml而言。
可以不指定template_dir，默认为None。
不指定template_dir表示不使用模板功能，此时后续的某个文档page项包含了template项，则会报错。

build_dir

生成的API文档所存放的文件夹。

build_dir支持相对路径。如果是相对路径则是相对于sophon.yml而言。
可以不指定build_dir，默认为./api，即在sophon.yml所在文件夹新建一个叫做api的文件夹来存放API文档。

repo_url

指定存放了源代码的仓库，可以在API文档中为每个API生成一个链接到源代码的超链接。

暂时仅支持GitHub。
格式为https://github.com/your_user_name/your_repo。
可以不指定repo_url，默认为None。
不指定repo_url表示不使用该功能。

branch

指定源代码仓库上的分支。

可以不指定branch，默认为master。
当不指定repo_url时，branch无效。

style

指定您Python代码中docstring所使用的风格。

目前支持sophon(google, numpy即将支持)。
可以不指定style，默认为sophon。

pages

pages是一个包含了0个或多个page的列表，包含了所有要生成的文档。更多详细用法请看page。

可以不指定pages，默认为None。
当不指定pages或指定了pages但是不包含任何page时，表示不生成任何文档。

page

page表示一个生成的API Markdown文档。格式为：

# filename: /home/user/sophon.yml
build_dir: api
template_dir: templates

pages:
- page: test/aa.md
  template: bb.md
- page: cc.md
  template: test/dd.md

每个page必须指定文件路径名，该文件路径名必须是相对路径，且是相对于build_dir而言。
在上面的例子中，Sophon会按顺序：
- 生成路径名为/home/user/api/test/aa.md的API文档，所使用的模板文件为/home/user/templates/bb.md。
- 生成路径名为/home/user/api/cc.md的API文档，所使用的模板文件为/home/user/templates/test/dd.md。

tag

tag表示一个标记，通常结合模板文件来使用，表示生成的API Markdown text应该插入到模板文件的哪个地方。

举个例子,假设模板文件/home/user/templates/bb.md内容为：

# Hello World

{{tag0}}

## Hello Sophon

{{tag1}}

配置文件为：

# filename: /home/user/sophon.yml
build_dir: api
template_dir: templates

pages:
- page: test/aa.md
  template: bb.md
  tags:
  - tag: tag0
    functions:
    - mod.func
  - tag: tag1
    classes:
    - mod.clazz

则运行Sophon之后：

Sophon会先读取模板文件/home/user/templates/bb.md里的内容；
然后将标记{{tag0}}替换为函数mod.func的API Markdown text；
再将标记{{tag1}}替换为类mod.clazz的API Markdown text；
最后将内容写入/home/user/api/test/aa.md中。

注意的是，以下几种情况中，该tag下包含的函数、类的API Markdown text会依次添加在文件末尾，而不是替换掉模板文件中的{{tag}}：

配置文件中指定了一个tag，但是没有给tag名时；
配置文件中指定了一个tag，但是在模板文件中不存在该tag标记时；
配置文件中指定了一个tag，但是该tag所属的page没有使用模板文件时。

每个tag所包含的API按照固定顺序classes->classes_with_members->functions依次生成API Markdown text。

另外，Sophon不会对存在于模板文件但是却没有在配置文件中指定的tag作任何处理，也就是一切以配置文件为准。

classes

classes是一个包含多个类的包路径的列表。

Sophon在生成一个类的API文档时，只会选择该类的docstring来生成该类构造函数的API Markdown text，并不包括该类的成员函数与方法。

classes_with_methods

classes_with_methods是一个包含多个函数的包路径的列表。

Sophon在生成一个类的API文档时，会生成包括构造函数在内的该类所有公有成员函数与方法的API Markdown text。

functions

functions是一个包含多个函数的包路径的列表。