litedoc 0.1.0.dev20240904111448

Default template for PDM package

Litedoc

为你的Python库模块生成结构化的markdown文档

功能：

• i18n多语言支持
• frontmatter支持
• 可选注释风格
• 可选主题支持
• 支持对象带有相对链接跳转

安装

pip install litedoc

使用方法

litedoc <your_module_path> -o|--output <output_path>

详细命令参数

-o|--output: "doc-output"  输出路径，默认为doc-output
-l|--lang:   "zh-Hans"  语言，支持en, zh-Hans，zh-Hant，ja，默认zh-Hans
-t|--theme: "vitepress"  主题，支持vitepress, vuepress, 默认vitepress
-s|--style: "google"  风格，支持google, numpy, reStructuredText, 默认google，但目前只实现了google，欢迎PR
-f|--frontmatter:  #是否生成frontmatter，即文档的元数据，如title, description等, 格式为key1=value1,key2=value2, 空格用%20代替
-b|--base-url: ""  基础URL，用于生成文档中的跳转链接，通常指向Github仓库下的包路径根目录，
    如果为空字符串将不生成，末尾带/，例如https://github.com/snowykami/mbcp/tree/main/mbcp/
-fd|--function-define: "func" 函数定义风格，输出的markdown显示的函数定义，Python原生为def
-md|--method-define: "method" 方法定义风格，输出的markdown显示的方法定义
-cd|--class-define: "class" 类定义风格，输出的markdown显示的类定义
-vd|--var-define: "var" 变量定义风格，输出的markdown显示的变量定义
-ad|--attr-define: "attr" 属性定义风格，输出的markdown显示的属性定义
-c|--contain-top    # 是否包含顶部文件夹信息，即在输出目录再套一层module_path的basedir
-cs|--create-same  # 是否在包下创建和包名相同的md文件储存__init__文件的内容(有同名文件时请勿使用，例如client/client.py)

在输出的目录下markdown文档是以模块原有的目录结构生成的，可以直接把输出内容放到目前主流的文档框架项目中，如VuePress，VitePress等，如果想优化用户体验，还可启用动态侧边栏

代码编写建议

• 在编写函数的时候，请写上标准的注释，这样对用户和自己都有好处
  • 代码遵循相应的PEP规范，如PEP8，PEP257等
  • 可在文件头部使用"""包裹的注释写上文件的说明，会被自动放到文档的顶部
  • 请不要在注释中使用特殊字符例如换行符\n，如有请使用\\n转义或使用原始字符串r"""string content"""，否则会导致解析错误
  • 可以在注释中编写一些你所使用的文档框架支持的markdown增强语法，如表格，容器等，可增强用户阅读体验
  • 可在参数注释中使用markdown的链接语法和哈希路由，如p ([`Point3`](./point#class-point3)): 点，以支持跳转到其他文档的链接
• 生成器默认不处理"私有"变量和函数，即以_开头的变量和函数（尽管Python没有真正的私有变量），也默认不处理没有注释的变量
• 如果你不想展示某个函数和变量，可以在函数文档字串任意处加上@litedoc-hide
• 变量注释支持在同一行内使用#添加的注释，也支持在下一行使用"""注释内容"""添加的注释
• 可在文件顶部的注释顶部添加frontmatter，如---\ntitle: liteyuki\n---，会被自动追加更新到传入的frontmatter中

自动化构建(Github workflows)

• 如果你了解并正在使用github workflow自动构建文档，那么可以把生成API markdown的步骤也添加进去，无需手动生成文档。
• 需在构建静态页面之前生成API markdown

...
- name: Set up Python
  uses: actions/setup-python@v2
  with:
    python-version: '3.10'


- name: Build API markdown
  run: |-
    python -m pip install litedoc
    litedoc <your_module> -o docs/dev/api -l zh-Hans -t vuepress
    litedoc <your_module> -o docs/en/dev/api -l en -t vuepress'   # 请自行更改这部分
    # ...可以添加更多语言
...
# build your static page

示例项目

• 轻雪文档

• MBCP Docs

其他

Liteyuki Docstring

Liteyuki Docstring是Google风格docstring的超集，可以更好地配合Litedoc生成更美观的文档 支持

• @litedoc-hide 隐藏函数或变量
• 链接跳转（需文档框架支持）
• 更多的markdown语法

示例

• 以下是一个Google docstring示例

def add(a: int, b: int) -> int:
    """
    This is a function to add two numbers
    Args:
        a: The first number
        b: The second number
    Returns:
        The sum of a and b
    """
    return a + b

• 以下是一个Liteyuki docstring示例

def add(a: int, b: int) -> int:
    """
    This is a function to add two numbers
    Args:
        a ([`int`](https%3A//docs.python.org/3/library/functions.html#int)): The first number
        b (`int`) : The second number
    Returns:
        [`int`](https%3A//docs.python.org/3/library/functions.html#int): The sum of a and b
    @litedoc-hide
    """
    return a + b

• 还可以在模块内部使用相对链接和哈希路由跳转到其他文档

def add(a: int, b: int) -> int:
    """
    This is a function to add two numbers
    Args:
        a ([`int`](./int#class-int)): The first number
        b (`int`) : The second number
    Returns:
        [`int`](./int#class-int): The sum of a and b
    """
    return a + b

以上写法不影响主流编辑器的Google docstring解析，但可以更好地配合Litedoc生成更美观的文档

Python函数参数

• 一个Python函数可以有五种传参方式：仅位置参数(posonlyargs)、位置参数(args)、可变参数(vararg)、仅关键字参数(kwonlyargs)及关键字参数(kwarg)。以下是一个函数的参数的例子。

代码示例

def example1(poa1, poa2, /, a1, a2, *args, kwoa1, kwoa2, **kwargs):
    """
    这是一个示例函数
    Args:
        poa1: 仅位置参数1
        poa2: 仅位置参数2，此后的/用于分隔仅位置参数，在/之前的只能使用位置参数传参
        a1: 位置参数3
        a2: 位置参数4
        args: 可变参数，在此之后定义的形参需要使用关键字传参
        kwoa1: 关键字参数1
        kwoa2: 关键字参数2
        kwargs: 关键字可变参数
    """

example1(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, kwoa1=11, kwoa2=12, kwoa3=13, kwoa4=14)
"""
传参结果
Posonlyargs:
    pos1: 1
    pos2: 2
Args:
    a1: 3
    a2: 4
Vararg:
    args: (5, 6, 7, 8, 9, 10)
Kwonlyargs:
    kwoa1: 11
    kwoa2: 12
Kwarg:
    kwargs: {'kwoa3': 13, 'kwoa4': 14}
"""


def example2(poa1, poa2, /, a1, a2, *, kwoa1, kwoa2):
    """
    这是一个示例函数
    Args:
        poa1: 仅位置参数1
        poa2: 仅位置参数2，此后的/用于分隔仅位置参数，在/之前的只能使用位置参数传参
        a1: 位置参数3
        a2: 位置参数4
        kwoa1: 关键字参数1
        kwoa2: 关键字参数2，此后的*用于分隔关键字参数，在*之后的只能使用关键字传参
    """
    pass


example2(1, 2, 3, 4, kwoa1=5, kwoa2=6)
"""
传参结果
Posonlyargs:
    pos1: 1
    pos2: 2
Args:
    a1: 3
    a2: 4
Kwonlyargs:
    kwoa1: 5
    kwoa2: 6
"""

相关PEP

• PEP 3102 - Keyword-Only Arguments
• PEP 570 - Python Positional-Only Parameters
• PEP 3107 - Function Annotations
• PEP 484 - Type Hints