开发文档

A document will helps you and others better understands your code. 文档会帮助代码的开发，完善以及协作。 我们使用sphinx帮助打包生成文档。文档为 rst 格式。 我们可以参考 request 库的文档，以及 github 源码。

除了了解rst的语法格式，一个好的函数文档开需要了解其规范和要求。 可以参考Google的函数文档 范例 。

rst语法

章节

章节的标定确定了页面的框架。在rst中，章节下面应该加上不短于标题的符号串。章节是分层次的，不同层次的章节由下面的符号串进行区分，一般推荐如下设计：

Header
=======

Section L2
-----------

Section L3
^^^^^^^^^^^^

Section L4/Paragraph
"""""""""""""""""""""

列表

• This is a bulleted list.
• It has two items, the second item uses two lines.

1. This is a numbered list.
2. It has two items too.
3. This is a numbered list.
4. It has two items too.

注意，需要在上面和下面加一个空行。

* This is a bulleted list.
* It has two items, the second
  item uses two lines.

1. This is a numbered list.
2. It has two items too.

#. This is a numbered list.
#. It has two items too.

代码

参考 sphinx 的说明。

.. code-block:: python
:emphasize-lines: 3,5

    def some_function():
       interesting = False
       print 'This line is highlighted.'
       print 'This one is not...'
       print '...but this one is.'

def some_function():
    interesting = False
    print 'This line is highlighted.'
    print 'This one is not...'
    print '...but this one is.'

图像

注意必须有一个空行在上面。

.. image:: ../_static/images.jpeg

表格

生成表格的简单方式

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

Inputs		Output
A	B	A or B
False	False	False
True	False	True
False	True	True
True	True	True

推荐使用csv table，可以指定标题，列名以及宽度，注意指令上需要空行；

.. csv-table:: A CSV Table
   :header: "Treat", "Quantity", "Description"
   :widths: 15, 10, 30

   "Albatross", 2.99, "On a stick!"
   "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
   crunchy, now would it?"
   "Gannet Ripple", 1.99, "On a stick!"

A CSV Table

Treat	Quantity	Description
Albatross	2.99	On a stick!
Crunchy Frog	1.49	If we took the bones out, it wouldn’t be crunchy, now would it?
Gannet Ripple	1.99	On a stick!

链接

链接文字末尾加”_”，前后有空格；另起一行记录链接的内容；

我们使用sphinx帮助打包生成文档。文档为 rst_ 格式。

.. _rst: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#literal-blocks

代码文档

清楚、准确、全面的描述一个函数的功能，实现方式以及调用方法，结果等需要满足一定的规范，下面的一些规则会帮助你写出更好的文档：

举个例子：

def module_level_function(param1, param2=None, *args, **kwargs):
    """This is an example of a module level function.

    Function parameters should be documented in the ``Args`` section. The name
    of each parameter is required. The type and description of each parameter
    is optional, but should be included if not obvious.

    If \*args or \*\*kwargs are accepted,
    they should be listed as ``*args`` and ``**kwargs``.

    The format for a parameter is::

        name (type): description
            The description may span multiple lines. Following
            lines should be indented. The "(type)" is optional.

            Multiple paragraphs are supported in parameter
            descriptions.

    Args:
        param1 (int): The first parameter.
        param2 (:obj:`str`, optional): The second parameter. Defaults to None.
            Second line of description should be indented.
        *args: Variable length argument list.
        **kwargs: Arbitrary keyword arguments.

    Returns:
        bool: True if successful, False otherwise.

        The return type is optional and may be specified at the beginning of
        the ``Returns`` section followed by a colon.

        The ``Returns`` section may span multiple lines and paragraphs.
        Following lines should be indented to match the first line.

        The ``Returns`` section supports any reStructuredText formatting,
        including literal blocks::

            {
                'param1': param1,
                'param2': param2
            }

    Raises:
        AttributeError: The ``Raises`` section is a list of all exceptions
            that are relevant to the interface.
        ValueError: If `param2` is equal to `param1`.

    """
if param1 == param2:
    raise ValueError('param1 may not be equal to param2')
return True

automodule

打包一个模块的说明文档。

.. autoclass:: baseq.bam.BAMTYPE
    :members:

autofunction

打包一个函数的说明文档。

.. autofunction:: baseq.bam.BAMTYPE

函数文档的示例

Barcode split into 16 files according to the valid barcode in the bcstats files.

#. Determine whether the last base mutates;
#. Filter by whitelist;

:param protocol: 10X/Dropseq/inDrop.
:param name: barcode_count.
:param bcstats: Valid Barcode.
:param output: (./bc_stats.txt)

Return:
    The splitted reads will be write to XXXX/split.AA.fa

autoclass

打包一个类的说明文档。

.. autoclass:: baseq.bam.BAMTYPE

click command

对于click command，使用如下方式生成文档

.. click:: baseq.drops.cmd:cli
   :prog: baseq-Drop
   :show-nested:

External hyperlinks, like Python_. .. _Python: http://www.python.org/