teedoc 插件开发
teedoc
的插件开发很简单, 目前只需要根据模板修改一下就可以实现新的功能, 如果会 python
html
css
js
则会更加简单。
插件的运行原理就是teedoc
提供插件 API, 写一个python
包, 继承这个类, 重写需要的方法(API
)即可, 具体每个方法的含义在插件 API文件中有详细的注释说明
如果发现 API 有不合理的地方, 可以提交 issue 来发起讨论, 一起完善~
一、参考模板#
可以参考默认的插件
二、插件目录结构#
这里以teedoc-plugin-baidu-tongji 为例
- 创建一个目录, 目录名和插件名相同, 建议以
teedoc-plugin-
开头,方便大家搜索到 - 然后创建一个
setup.py
文件, 这个是python
包的通用配置文件, 文件中最重要的就是执行setuptools.setup()
函数, 参数主要包含了一下几个,更多可以到python
官方文档查找
- 创建包
需要再创建一个子文件夹,用来存放源码,文件名将项目名称中的减号-
替换成下划线_
即可, 因为python
代码中要求包名不能用减号, 比如这里是teedoc_plugin_baidu_tongji
然后在里面新建一个文件__init__.py
- 编辑
__init__.py
要实现百度统计的功能, 实际就是向所有页面的<head></head>
标签中添加一段百度统计指定的脚本即可,即<script></script>
标签, 同时, 从文档配置中获取统计编号(code
), 代码如下:
可以看到class Plugin(Plugin_Base):
继承了Plugin_Base
类, 然后重写了on_init
和on_add_html_header_items
方法, teedoc
构建文档时,会在合适的时机调用这两个函数。
我们在on_init
初始化函数中从config
中获取到了百度统计的code
,然后生成了<script>
标签的内容存放到了html_header_items
中, 然后在on_add_html_header_items
函数中将其返回,这样teedoc
就会将这个标签添加到所有HTML
页面的<head>
标签中了
- 资源文件
可以在setup.py
中
指定将assets
目录及其下所有文件作为包数据文件拷贝到安装路径, 然后就可以在__init__.py
中使用相对路径(assets/
)访问到了,可以在API
的 on_copy_files
中将这个文件拷贝到输出目录, 可以看teedoc_plugin_search的做法, 其实就是返回了一个字典
关键字是要拷贝到的目标路径,值是文件的绝对路径, 然后我们就可以在其它HTML
页面中通过/static/js/search/search_main.js
这个路径引用到了
三、测试插件#
两种方法,
3.1. 一种是直接让teedoc
调用源码#
调试建议使用这种方法, 修改代码只需要重新执行teedoc serve
就可以生效
- 修改一份文档根目录的
site_config.json
文件,指定插件的来源为目录路径
然后在文档根目录执行teedoc serve
就可以了
3.2. 另一种方法是直接安装插件到系统,让teedoc
调用软件包#
使用这种方法, 修改代码需要每次更改代码都要来一遍下面的步骤,比上面一种方法麻烦,在发布插件前可以用这种方式测试一下可用性即可
- 安装插件
插件写好了通过在插件根目录(有setpu.py
文件的目录)下执行
注意.
符号不要忽略
插件就会作为一个python
包被安装到系统
- 然后在文档根目录执行
teedoc serve
就可以了
四、注意点#
因为构建是会用到多进程, 所以有些地方需要注意
- 插件初始化:
__init__()
函数不能重写,插件的初始化可以使用on_init()
或者on_new_process_init()
;on_init()
是在初始化插件时调用,一般的数据可以在这里面初始化。当多进程创建时,插件的数据会被拷贝到新的进程使用, 对于一些不能多进程直接拷贝使用的对象,请在on_new_process_init()
中初始化on_new_process_init()
是在创建多进程时调用, 比如这里就在这个函数里面来初始化markdown
渲染器而不是在on_init()
中,因为不希望在新进程创建时对self.md_parser
对象进行拷贝,而是每个新进程都独立重新创建一个对象
- 同样
__del__()
函数也不能使用, 而是使用on_del()
或者on_new_process_del()
函数 - 在plugin.py中
on_new_process_init()
后面的函数都是可能会在新进程(多进程)中调用的,前面的函数则只会在主进程中调用
五、发布插件#
插件的发布方式就是普通python
包的发布方式, 发布到pypi.org
- 在插件根目录执行命令生成发布包:
在pypi.org注册账号
然后上传到
pypi.org
- 然后用户就可以在
site_config.json
中直接填写你的插件名来使用了
也可以通过pip
安装:
Be the first person to leave a comment!