teedoc 插件开发 =========== `teedoc` 的插件开发很简单， 目前只需要根据模板修改一下就可以实现新的功能， 如果会 `python` `html` `css` `js` 则会更加简单。 插件的运行原理就是`teedoc` 提供[插件 API](https://github.com/teedoc/teedoc/blob/main/teedoc/plugin.py)， 写一个`python`包， 继承这个类， 重写需要的方法（`API`）即可， 具体每个方法的含义在[插件 API](https://github.com/teedoc/teedoc/blob/main/teedoc/plugin.py)文件中有详细的注释说明 > 如果发现 API 有不合理的地方， 可以[提交 issue](https://github.com/teedoc/teedoc/issues) 来发起讨论， 一起完善~ ## 参考模板 可以参考[默认的插件](https://github.com/teedoc/teedoc/tree/main/plugins) ## 插件目录结构 这里以[teedoc-plugin-baidu-tongji](https://github.com/teedoc/teedoc/tree/main/plugins/teedoc-plugin-baidu-tongji) 为例 * 创建一个目录， 目录名和插件名相同， 建议以`teedoc-plugin-`开头，方便大家搜索到 * 然后创建一个`setup.py`文件， 这个是`python`包的通用配置文件， 文件中最重要的就是执行`setuptools.setup()`函数， 参数主要包含了一下几个，更多可以到`python`官方文档查找 ```python setup( name='teedoc-plugin-baidu-tongji', version="1.0.2", author='Neucrack', author_email='xxx@xxx.com', description='baidu tongji plugin for teedoc', long_description=long_description, # can read from README.md long_description_content_type="text/markdown", url='https://github.com/Neutree/teedoc', license='MIT', # See https://pypi.python.org/pypi?%3Aaction=list_classifiers classifiers=[ # Indicate who your project is intended for 'Intended Audience :: Developers', # Pick your license as you wish (should match "license" above) 'License :: OSI Approved :: MIT License', # Specify the Python versions you support here. In particular, ensure # that you indicate whether you support Python 2, Python 3 or both. 'Programming Language :: Python :: 3' ], keywords='teedoc baidu tongji', # List run-time dependencies here. These will be installed by pip when # your project is installed. For an analysis of "install_requires" vs pip's # requirements files see: # https://packaging.python.org/en/latest/requirements.html install_requires=install_requires, # List additional groups of dependencies here (e.g. development # dependencies). You can install these using the following syntax, # for example: # $ pip install -e .[dev,test] extras_require={ # 'dev': ['check-manifest'], # 'test': ['coverage'], }, # You can just specify the packages manually here if your project is # simple. Or you can use find_packages(). packages=packages, # If there are data files included in your packages that need to be # installed, specify them here. If using Python 2.6 or less, then these # have to be included in MANIFEST.in as well. package_data={ "teedoc_plugin_baidu_tongji" : ['assets/*'], }, # Although 'package_data' is the preferred approach, in some case you may # need to place data files outside of your packages. See: # http://docs.python.org/3.4/distutils/setupscript.html#installing-additional-files # noqa # In this case, 'data_file' will be installed into '/my_data' data_files=[ ], # To provide executable scripts, use entry points in preference to the # "scripts" keyword. Entry points provide cross-platform support and allow # pip to create the appropriate form of executable for the target platform. entry_points={ # 'console_scripts': [ # # 'gui_scripts': [ # 'teedoc=teedoc-plugin-markdown-parser.main:main', # ], }, ) ``` * 创建包 需要再创建一个子文件夹，用来存放源码，文件名将项目名称中的减号`-`替换成下划线`_`即可， 因为`python`代码中要求包名不能用减号， 比如这里是`teedoc_plugin_baidu_tongji` 然后在里面新建一个文件`__init__.py` * 编辑`__init__.py` 要实现百度统计的功能， 实际就是向所有页面的``标签中添加一段百度统计指定的脚本即可，即``标签， 同时， 从文档配置中获取统计编号（`code`）， 代码如下： ```python import os, sys from teedoc import Plugin_Base from teedoc import Fake_Logger class Plugin(Plugin_Base): name = "teedoc-plugin-baidu-tongji" desc = "baidu tongji support for teedoc" defautl_config = { } def on_init(self, config, doc_src_path, site_config, logger = None): ''' @config a dict object @logger teedoc.logger.Logger object ''' self.logger = Fake_Logger() if not logger else logger self.doc_src_path = doc_src_path self.site_config = site_config self.config = Plugin.defautl_config self.config.update(config) self.logger.i("-- plugin <{}> init".format(self.name)) self.logger.i("-- plugin <{}> config: {}".format(self.name, self.config)) # set site_root_url env value if not "code" in config: self.logger.e('can not find config["code"] in plugin {}'.format(self.name)) return baidu_tongji_code = ''''''.format(config["code"]) self.html_header_items = [baidu_tongji_code] def on_add_html_header_items(self): return self.html_header_items ``` 可以看到`class Plugin(Plugin_Base):`继承了`Plugin_Base`类， 然后重写了`on_init`和`on_add_html_header_items`方法， `teedoc`构建文档时，会在合适的时机调用这两个函数。 我们在`on_init`初始化函数中从`config`中获取到了百度统计的`code`，然后生成了`