Learn ESP-ADF

学习 ESP-ADF 框架.

• 阅读文档
• 工具安装
• 生成文档

工具安装

安装生成文档的工具。除非你要自已在本地生成文档，你才要执行这一步。

准备

• 安装 Python （sphinx 需要）。

安装 Sphinx

1. 安装软件包（需要先安装 Python）

    pip install sphinx sphinx_intl sphinx_rtd_theme recommonmark plantweb

   • sphinx: 文档生成工具
   • sphinx_intl: 多语言工具
   • recommonmark: sphinx支持markdown的插件
   • sphinx_rtd_theme: sphinx的readthedocs主题插件

   • plantweb: uml 生成工具

2. 创建存放文档的目录，执行 sphinx-quickstart 命令

    cd /path/to/project
    mkdir docs
    cd docs
    sphinx-quickstart

   sphinx-quickstart 会创建基本配置。一般情况下，你只要接受默认值就行了。当上述命令执行完后，在 docs目录下，你会找以 index.rst和 conf.py。 你可以编辑这两个文件，加入一些项目信息。

   • Makefile : 批处理指令，使用 make 命令时，用来构建文档输出。
   • _build : 用于存放最终生成的文档。
   • _static : 所有不属于文档源代码的文件（如图像）均存放于此处，构建时会它们链接在一起。
   • conf.py : 一个 Python 文件，存放 Sphinx 的配置值，包括执行 sphinx-quickstart 时选中的那些值。

   • index.rst : 文档项目的 root 目录。如果将文档有多个文件，该目录会连接这些文件。

3. 修改conf.py，加入 Markdown 支持，UML 支持

    extensions = ['recommonmark']
    extensions = ['plantweb.directive']

4. 修改 conf.py，使用 sphinx_rtd_theme 风格。修改

    html_theme = 'alabaster'

   为

    import sphinx_rtd_theme
    html_theme = "sphinx_rtd_theme"
    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

本地生成文档

在 docs\ 目录下执行命令，则生成 html 格式输出

make html

输出的html文件在 docs\_build\html目录下， 打开 index.html即可。

LICENSE

Learn ESP-ADF 采用 Apache-2.0 License 授权。

——END——