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。
- 生成路径名为
tags
tags是一个包含了0个或多个tag的列表，也是page的成员。更多详细用法请看tag。
- 可以不指定
tags，默认为None。 - 当不指定
tags或指定了tags但是不包含任何tag时，Sophon不会向该tags所属page文件中生成任何Markdown text。
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是一个包含多个函数的包路径的列表。