python学习笔记一（ 1.基础知识-注释）

目录

1. 注释
2. 变量与数据类型
3. 基本输入输出
4. 操作符

注释

基础

• 单行注释（#）
  单行注释占一行的为块注释，注释占行尾的为块注释

# 这是一个块注释
x = 10  # 这是一个行内注释

• 多行注释（‘’‘’‘’）
  行内注释使用三个引号包裹，单引号(')和双引号(")等价

'''
这是一个多行注释
它可以跨越多行
但实际上是一个多行字符串
'''

进阶

文档字符串
文档字符串与多行注释的注释方法相同，可以通过__doc__属性访问，可用于自动化生成文档。

例

def my_function():
    """
    这是一个简单的函数示例。
    :return: 返回一个字符串。
    """
    return "Hello, World!"

class MyClass:
    """
    这是一个示例类。
    """
    def method(self):
        """
        这是类中的一个方法。
        """
        pass

# 访问函数的文档字符串
print(my_function.__doc__)

# 访问类的文档字符串
print(MyClass.__doc__)

# 访问方法的文档字符串
print(MyClass.method.__doc__)

控制台将打印处注释内容。

文档生成工具

• pydoc
  pydoc是Python内置的工具，用于从docstring生成文档。可以通过命令行使用 pydoc 生成模块、类、函数的文档，并可以输出为HTML文件。

# 生成文档
pydoc my_module
# 生产html文档
pydoc -w my_module

• Sphinx
  Sphinx 是一个强大的文档生成工具，通常用于为Python项目生成HTML、LaTeX、PDF等格式的文档。它能够解析docstring并自动生成文档。

# 安装sphinx
pip install sphinx

#初始化sphinx项目
sphinx-quickstart

# 生成文档
# 在conf.py文件中配置项目路径
sphinx-apidoc -o docs/source path_to_your_package
sphinx-build -b html docs/source docs/build

• docstring-to-markdown
  docstring-to-markdown可以将Python文件中的docstring转换为Markdown格式。

# 安装docstring-to-markdown
pip install docstring-to-markdown

# 生成Markdown文档
docstring-to-markdown my_module.py > my_module.md