Pre-release
This release is a pre-release and may not be stable for production use.
Litedoc
为你的Python库模块生成结构化的markdown文档
功能：
- i18n多语言支持
- 可选注释风格
- 可选主题支持
安装
pip install litedoc
使用方法
python -m 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代替
-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增强语法，如表格，容器等，可增强用户阅读体验
- 生成器默认不处理"私有"变量和函数，即以
_开头的变量和函数（尽管Python没有真正的私有变量），也默认不处理没有注释的变量 - 如果你不想展示某个函数和变量，可以在函数文档字串任意处加上
@litedoc-hide - 变量注释支持在同一行内使用
#添加的注释，也支持在下一行使用"""注释内容"""添加的注释
自动化构建(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
python -m litedoc <your_module> -o docs/dev/api -l zh-Hans -t vuepress
python -m litedoc <your_module> -o docs/en/dev/api -l en -t vuepress' # 请自行更改这部分
...
# build your static page
示例项目
其他
函数参数
- 一个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
1 maintainer
Metadata
1 maintainer
Release files for litedoc 0.1.0.dev20240830212606
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| litedoc-0.1.0.dev20240830212606.tar.gz | 27.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| litedoc-0.1.0.dev20240830212606-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 46.9 kB
Release files / litedoc-0.1.0.dev20240830212606.tar.gz
| Download URL | litedoc-0.1.0.dev20240830212606.tar.gz |
|---|---|
| Size | 27.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3aa6a416853f8e8ce633beadc489f1610f54a7e838ca4df31743d30ba8fd22a0
|
|
BLAKE2b-256 checksum How to use checksums |
3608542c94b5f2760f5c5bc118a138e4ba75471c4363f9addec141ddc5f54a4c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
pdm/2.18.1 CPython/3.10.12 Linux/6.5.0-1025-azure
|
Release files / litedoc-0.1.0.dev20240830212606-py3-none-any.whl
| Download URL | litedoc-0.1.0.dev20240830212606-py3-none-any.whl |
|---|---|
| Size | 19.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fcf00da56ef688e62b7bae6a3c5d282de51f512d19ef8776244f6af6a1478dc4
|
|
BLAKE2b-256 checksum How to use checksums |
5352ebc7c00e301ed1700b6a3b9ee5850065df8bba2b2f29d88aa064f4c7080b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
pdm/2.18.1 CPython/3.10.12 Linux/6.5.0-1025-azure
|
