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

示例项目

Metadata

Release files for litedoc 0.1.0.dev20240830020647

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for litedoc 0.1.0.dev20240830020647
File	Size	Uploaded
litedoc-0.1.0.dev20240830020647.tar.gz	24.5 kB	Aug 30, 2024	Details

Built distribution (wheel)

Table of built distributions (wheels) for litedoc 0.1.0.dev20240830020647
File	Interpreter	ABI	Platform	Reset
litedoc-0.1.0.dev20240830020647-py3-none-any.whl 18.3 kB Aug 30, 2024	Python 3	none	any	Details

Total release size: 42.7 kB

Release files / litedoc-0.1.0.dev20240830020647.tar.gz

Download URL	litedoc-0.1.0.dev20240830020647.tar.gz
Size	24.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`a306e5c3cc6bbb2954df4ab16f751dc2be8d5e02efb6fc83af74e31e81338178`
BLAKE2b-256 checksum How to use checksums	`6326f418368ce60eb3e0ab75648b36ef3c45c8982eeb968da9caf216dbc2f96e`
Upload date	Aug 30, 2024
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.dev20240830020647-py3-none-any.whl

Download URL	litedoc-0.1.0.dev20240830020647-py3-none-any.whl
Size	18.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c50e6ed5aef99830a1d6e3ef0eedffafc46880af6e2041dad2ec57ceb7cdbc84`
BLAKE2b-256 checksum How to use checksums	`1e16a83ded6e9fce88f412e292a65d8a28e94c3e6c5e98eab637d050d1a4d6b8`
Upload date	Aug 30, 2024
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`