Default template for PDM package
Project description
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
-c|--contain-top #是否包含顶部文件夹信息,即在输出目录再套一层module_path的basedir
在输出的目录下markdown文档是以模块原有的目录结构生成的,可以直接把输出内容放到目前主流的文档框架项目中,如VuePress,VitePress等,如果想优化用户体验,还可启用动态侧边栏
代码编写建议
- 在编写函数的时候,请写上标准的注释,这样对用户和自己都有好处
- 可在文件头部使用
"""
包裹的注释写上文件的说明,会被自动放到文档的顶部 - 请不要在注释中使用特殊字符例如换行符
\n
,如有请使用\\n
转义后,否则会导致解析错误 - 可以在注释中编写一些你所使用的文档框架支持的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
示例项目
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Close
Hashes for litedoc-0.1.0.dev20240830014937.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 84cc90583bbac3be7ad0f0d2e1efba3030e5cc4f67785f518f1644f56d49bf5f |
|
MD5 | 15e5040f8915db00b5d76040667d0732 |
|
BLAKE2b-256 | 2b8e8162f92228bfc6433be3fadbd2124662ba93e2b4b78877701a9201d1399f |
Close
Hashes for litedoc-0.1.0.dev20240830014937-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a6a3ece074464a849292468e7737208b9391d9d089ad7423a0582c7d9a2309d9 |
|
MD5 | eb6008ca1d0620b816ae0f4a7482a504 |
|
BLAKE2b-256 | fc9ed40db02cf67ed8f1825172fb1a6d49e2768e87b7418e397cf4c94f02bdd6 |