Created 用reStructuredText语法为代码写注释 (markdown)

master
lyhuang18 6 years ago
parent
commit
0a14e9dd50
1 changed files with 86 additions and 0 deletions
  1. +86
    -0
      用reStructuredText语法为代码写注释.md

+ 86
- 0
用reStructuredText语法为代码写注释.md

@@ -0,0 +1,86 @@
## 例子
```python
def my_function(my_arg, my_other_arg):
"""A function just for me.
:param my_arg: The first of my arguments.
:param str my_other_arg: The second of my arguments.
:returns: A message (just for me, of course).
This is an example::
[
[[word_11, word_12, word_13], [label_11. label_12]], # sample 1
[[word_21, word_22, word_23], [label_21. label_22]], # sample 2
...
]

This is an example:
>>> a=1
>>> b=2
>>> a+b
3

.. note::
This is a note.
"""
```
### Tips:
1. 在`:param arg:`前必须空一行,才能显示出参数和返回值列表;在arg前面可以加上变量类型
2. `::`标记如果作为独立段落存在,则整段都不会出现在文档里;如果前面有空白,则标记被移除;如果前面是非空白,则标记被一个冒号取代。
3. `.. note::`能生成一个note


## 其他可能会用到的

### **列表**

使用`*`号表示一组列表,`#.`表示有序列表,例子如下:

```
* 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.123456789
```

### 行内标记

```
*text* 斜体
**text** 加粗
``text`` 代码引用
```

### 代码片段

如果是python代码,直接段落后面加 `::`,并留一空行,被引用的代码,还要以tab或等量的空格进行缩进,如下面例子:

```
python使用如下语法定义list,list的元素类型可以不一样::

>>> a = ['spam', 'eggs', 100, 1234]
>>> a
['spam', 'eggs', 100, 1234]12345
```

### **代码包含**

引用外部的源代码文件,例子如下:

```
.. literalinclude:: ../code/threading_1.py
:language: python
:linenos:
:lines: 1,3,5-10,20-1234
```

显示代码方面的更详细的资料,可以查看 <http://www.pythondoc.com/sphinx/markup/code.html>

Loading…
Cancel
Save