如何在keystone项目中编写API文档

keystone的API文档存放在api-ref目录下，如下图所示：

1. conf文件是项目的配置文件，如下图所示：
   

2. index.rst是最外层的目录文件。
   

   reStructuredText 是扩展名为.rst的纯文本文件，含义为”重新构建的文本”“，也被简称为：RST或reST；是Python编程语言的Docutils项目的一部分，Python Doc-SIG (Documentation Special Interest Group)。该项目类似于Java的JavaDoc或Perl的POD项目。 Docutils 能够从Python程序中提取注释和信息，格式化成程序文档。
   .rst 文件是轻量级标记语言的一种，被设计为容易阅读和编写的纯文本，并且可以借助Docutils这样的程序进行文档处理，也可以转换为HTML或PDF等多种格式，或由Sphinx-Doc这样的程序转换为LaTex、man等更多格式。

3. 几种常见的语法介绍
   “..”表示注释，不会在html文件中出现。

.. keystone documentation master file, created by
   sphinx-quickstart on Mon May 23 07:54:13 2016.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

文档标题

Welcome to keystone's documentation!
====================================
====================================
Welcome to keystone's documentation!
====================================

下图表示的是上面生成的一级标题跟二级标题

标题最多分六级，可以自由组合使用。具体见RST语法

1. toctree

.. toctree::
    :maxdepth: 2

    v2/index
    v2-admin/index
    v2-ext/index
    v3/index
    v3-ext/index

toctree字段可以显示文档的目录层级，maxdepth表示最多能够显示多少级目录。

maxdepth=1

maxdepth=2

v3/index.rst文档开头有个 :tocdepth: 2 字段，这里控制的是这个页面左侧搜索树的层级（默认不填，则全部显示）

tocdepth不填

tocdepth: 1

v2/index 代表引用v2目录下的index.rst文件，可以链接到v2下的index文件。