V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
爱意满满的作品展示区。
guyskk
V2EX  ›  分享创造

Python 魔法: 给 MKDocs 添加 autodoc 插件,并且支持自定义主题

  •  
  •   guyskk ·
    guyskk · 2016-10-24 03:04:02 +08:00 · 3559 次点击
    这是一个创建于 2712 天前的主题,其中的信息可能已经有所发展或是发生改变。

    之前项目文档是用 reStructuredText 格式写的,但是这个语法比较复杂,还是更喜欢用 Markdown 写。 这几天把文档从 Sphinx 迁移到 MKDocs ,还是托管在 ReadTheDocs 上面,遇到几个坑。

    1. MKDocs 没有 autodoc 插件,而且还没有插件 API Issue。 其实是有一个 autodoc 插件的,但是 MKDocs 没有插件 API ,那个插件作者只好把 MKDocs 代码给改了, 到现在已经大半年了插件 API 还没搞定。。。这样也就没法在 ReadTheDocs 上使用。

    2. 托管到 ReadTheDocs 上只能用 ReadTheDocs 的主题,Issue
      At present the theme is hard-coded: https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/doc_builder/backends/mkdocs.py#L147

    研究了两天源码,最后用 Hack 手段搞定,核心代码:

    @patch(build.build)
    def patched_build(f, config, *args, **kwargs):
        print("HACK".center(60, "-"))
        real_config = load_config(config_file=None)
        for k in ["theme", "theme_dir"]:
            config[k] = real_config[k]
        return f(config, *args, **kwargs)
    

    运行时修改 build 函数

    PATCHED = {}
    
    
    def patch(f_be_patched):
        def decorater(f):
            key = str(uuid.uuid4())
            PATCHED[key] = functools.partial(f, copy_func(f_be_patched))
            code = """
    def wrapper(*args, **kwargs):
        return __import__("magicpatch").PATCHED["{}"](*args, **kwargs)
            """.format(key)
            context = {}
            exec(code, context)
            f_be_patched.__code__ = context["wrapper"].__code__
            return f
        return decorater
    

    这句f_be_patched.__code__ = context["wrapper"].__code__比较魔性,直接修改函数定义, 但是有限制, locals,globals,closure 这些必须一致(无法修改),也就是只能使用原有的函数能用的变量。

    完整代码在这: https://github.com/restaction/mkdocs-autodoc
    Demo: http://restaction.readthedocs.io/zh_CN/latest/api/

    1 条回复    2016-10-24 13:01:19 +08:00
    vibiu
        1
    vibiu  
       2016-10-24 13:01:19 +08:00 via Android
    python 的魔法确实很多
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   4782 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 26ms · UTC 09:58 · PVG 17:58 · LAX 02:58 · JFK 05:58
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.