Skip to main content

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

litedoc-0.1.0.dev20240830021135.tar.gz (24.5 kB view details)

Uploaded Source

Built Distribution

litedoc-0.1.0.dev20240830021135-py3-none-any.whl (18.3 kB view details)

Uploaded Python 3

File details

Details for the file litedoc-0.1.0.dev20240830021135.tar.gz.

File metadata

  • Download URL: litedoc-0.1.0.dev20240830021135.tar.gz
  • Upload date:
  • Size: 24.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: pdm/2.18.1 CPython/3.10.12 Linux/6.5.0-1025-azure

File hashes

Hashes for litedoc-0.1.0.dev20240830021135.tar.gz
Algorithm Hash digest
SHA256 4a3805beb9d73e0c519d824dd0aa3b25e500159274b264a24e4beedfc6f80aed
MD5 56108c0cd0bce1c066c56f6dc4a3c782
BLAKE2b-256 7fdd5bb8ccabef0dde6b8df48625ef4fd3ef2ae04adbdef22a3342082e9b19f1

See more details on using hashes here.

Provenance

File details

Details for the file litedoc-0.1.0.dev20240830021135-py3-none-any.whl.

File metadata

File hashes

Hashes for litedoc-0.1.0.dev20240830021135-py3-none-any.whl
Algorithm Hash digest
SHA256 acc37d36aad9bb100d7131285333434bc32d623ea87efc3df8a14577902f4187
MD5 79fa3ccbc979579234e75d17547c5207
BLAKE2b-256 32ef09f895b8e7397b810a74f7733562fdedd2686ff9bef1f9c50952fb6f49b9

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page