sphinx
*************************

:gitee: https://gitee.com/luzhenxiong/docs-sphinx

参与贡献
=================================

调试技巧
----------------------------------

https://www.sphinx-doc.org/en/master/internals/contributing.html#debugging-tips

html主题
=================================

https://www.sphinx-doc.org/en/master/usage/theming.html

心水主题: sphinx-rtd-theme

核心配置

* html_theme
* html_theme_options

sphinx-rtd-theme源码分析
-----------------------------------------

.. tip::

    了解主题源码有利于参与主题的开源贡献

`tag2.0.0 <https://github.com/readthedocs/sphinx_rtd_theme/tree/2.0.0>`_

技术栈分析

* 使用Sass编写的css样式
* 使用webpack作为前端开发和构建工具

核心文件

.. code-block:: text

    theme.conf ; 主题配置文件, 新版sphinx推荐使用 ``.toml`` 格式: https://www.sphinx-doc.org/en/master/development/html_themes/index.html#theme-configuration-theme-toml
    static ; 静态资源文件, 包括css, js, img等
    *.html ; 主题模板文件, 名称是约定号的

事件机制
====================================

https://www.sphinx-doc.org/en/master/extdev/event_callbacks.html

应用场景: autodoc插件用 `autodoc-skip-member <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#skipping-members>`_ 事件忽略指定的方法

conf.py
.. code-block:: python

    def autodoc_skip_member(app, what, name, obj, skip, options):
        if name == "write":
            # 不生成write方法的文档
            return True


    def setup(app):
        # 注册回调方法
        app.connect('autodoc-skip-member', autodoc_skip_member)

index.rst
.. code-block:: rst

    .. autoclass:: io.TextIOWrapper
       :members:

.. seealso::

    相关issue(open状态): https://github.com/sphinx-doc/sphinx/issues/12674