CSTOS

人生苦短 Python水深

0%

Python-文档生成与撰写

发表于 更新于 分类于
本文字数： 1.8k 阅读时长 ≈ 7 分钟

Python 进行文档生成，代码展示相关的实践。如

  • JupyterLab：程序员的笔记本神器，数据科学生产工具，基于 web 的集成开发环境，Jupyter Notebook 的下一代产品
    • Jupyter：Jupyter Notebook：交互式笔记本
  • sphinx：python 文档生成器
  • MKDocs：对 Markdown 友好的文档生成器
  • pelican：Python 编写的博客静态生成,
  • zeppelin：用于交互式数据分析的网页开源框架

概述

JupyterLab

JupyterLab：程序员的笔记本神器，数据科学生产工具，基于 web 的集成开发环境，Jupyter Notebook 的下一代产品

Jupyter：Jupyter Notebook：交互式笔记本
Pyodide：在浏览器端实现 Python 全栈科学计算。目测没有 Jupyter lab 好用，先 OUT.

  • 功能：
    • 终端：交互式代码运行、丰富的输出
    • 文本文件：Markdown, Python, R, LaTex（10 多种编程语言）
    • 模块化界面：如同 IDE 般，以档签形式打开多个 notebook 或文件
    • 镜像 notebook 输出：轻易地创建仪表板
  • 增强的 notebook 功能
    • Python 交互模式：直接输入代码然后执行并得到结果，用于 Python 调试。
    • 查看 csv、图片等
    • 更多插件支持：画流程图、写代码、写文档

基本使用

Jupyter

在想要运行的目录下 jupyter notebook

1
2
3
4
5
6
# 测试 matplotlib
import matplotlib.pyplot as plt
import numpy as np
x=np.arange(20)
y=x**2
plt.plot(x,y)
1
%lsmagic

快捷键

  • Command 模式：单元框线为灰色，输入程序命令，可快捷键操作
  • Edit 模式：输入代码或文本到活动单元
命令模式 (按键 Esc 开启)
  • Enter : 转入编辑模式 pythpy
  • Shift-Enter : 运行本单元，选中下个单元
  • Ctrl-Enter : 运行本单元
  • Alt-Enter : 运行本单元，在其下插入新单元
  • Y : 单元转入代码状态
  • M : 单元转入 markdown 状态
  • R : 单元转入 raw 状态
  • 1 : 设定 1 级标题
  • 2 : 设定 2 级标题
  • 3 : 设定 3 级标题
  • 4 : 设定 4 级标题
  • 5 : 设定 5 级标题
  • 6 : 设定 6 级标题
  • Up : 选中上方单元
  • K : 选中上方单元
  • Down : 选中下方单元
  • J : 选中下方单元
  • Shift-K : 扩大选中上方单元
  • Shift-J : 扩大选中下方单元
  • A : 在上方插入新单元
  • B : 在下方插入新单元
  • X : 剪切选中的单元
  • C : 复制选中的单元
  • Shift-V : 粘贴到上方单元
  • V : 粘贴到下方单元
  • Z : 恢复删除的最后一个单元
  • D,D : 删除选中的单元
  • Shift-M : 合并选中的单元
  • Ctrl-S : 文件存盘
  • S : 文件存盘
  • L : 转换行号
  • O : 转换输出
  • Shift-O : 转换输出滚动
  • Esc : 关闭页面
  • Q : 关闭页面
  • H : 显示快捷键帮助
  • I,I : 中断 Notebook 内核
  • 0,0 : 重启 Notebook 内核
  • Shift : 忽略
  • Shift-Space : 向上滚动
  • Space : 向下滚动
编辑模式 ( Enter 键启动)
  • Tab : 代码补全或缩进
  • Shift-Tab : 提示
  • Ctrl-] : 缩进
  • Ctrl-[ : 解除缩进
  • Ctrl-A : 全选
  • Ctrl-Z : 复原
  • Ctrl-Shift-Z : 再做
  • Ctrl-Y : 再做
  • Ctrl-Home : 跳到单元开头
  • Ctrl-Up : 跳到单元开头
  • Ctrl-End : 跳到单元末尾
  • Ctrl-Down : 跳到单元末尾
  • Ctrl-Left : 跳到左边一个字首
  • Ctrl-Right : 跳到右边一个字首
  • Ctrl-Backspace : 删除前面一个字
  • Ctrl-Delete : 删除后面一个字
  • Esc : 进入命令模式
  • Ctrl-M : 进入命令模式
  • Shift-Enter : 运行本单元，选中下一单元
  • Ctrl-Enter : 运行本单元
  • Alt-Enter : 运行本单元，在下面插入一单元
  • Ctrl-Shift– : 分割单元
  • Ctrl-Shift-Subtract : 分割单元
  • Ctrl-S : 文件存盘
  • Shift : 忽略
  • Up : 光标上移或转入上一单元
  • Down : 光标下移或转入下一单元
  • A：上方插入新单元
  • B：下方插入新单元
  • DD：删除选中单元
  • Z：撤销已删除的单元
  • Y：单元转入 Edit 模式
  • shift+up/down：选中多个单元
  • Shift+M：合并选中单元
  • F：查找与替换
  • Ctrl+Home：到单元开头
  • Ctrl+S：文件存盘
  • Ctrl+Enter：运行本单元
  • Alt+Enter：运行本单元，在下

Jupyterlab

1
2
3
4
pip install jupyterlab
# 开启
jupyter-lab
jupyter lab
1
2
3
4
5
6
# 生成密码
from notebook.auth import passwd
passwd()
c.NotebookApp.allow_root = True
c.NotebookApp.open_browser = False
c.NotebookApp.password = '刚才复制的一串数字粘贴到这里'

快捷键

  • tab：提示
  • shift + tab：函数文档查看

插件

1
2
3
4
# 以安装一个生成目录的插件为例
jupyter labextension install @jupyterlab/toc
# 查看安装的插件
jupyter labextension list
  • jupyterlab-manager
  • latex
  • toc：目录插件，展示 notebook 或 markdown 目录
  • jupyterlab_html
  • jupyterlab_code_formatter
  • jupyterlab_tensorboard
  • jupyterlab-drawio

遇到的问题

  • 问题：jupyter 拒绝了我们的连接请求

  • 解决方案：

    1
    jupyter notebook --ip=xx.xx.xxx.xxx

sphinx

sphinx：python 文档生成器

  • Spinx 本身不支持.md 文件生成文档，需要我们使用第三方库 recommonmark 进行转换。
    • So, MKDocs

MKDocs

MKDocs：对 Markdown 友好的文档生成器

1
2
3
4
5
6
7
uv pip install mkdocs -U
uv pip install "mkdocstrings[python]" -U
uv pip install mkdocs-material -U
uv pip install markdown-checklist -U

mkdocs new project_name
mkdocs serve
  • docs 文件夹：存放所有 markdown 文件
    • docs/index.md：首页入口
  • mkdocs.yml：配置

pelican

pelican：Python 编写的博客静态生成,

安装与配置

1
2
3
4
5
6
7
8
pip install pilican markdown typogrify
cd
mkdir blog
cd blog
cirtualenv pelican
cd pelican
sh bin/activate
pelican-quick start
  • content 文章目录
  • develop_server.sh 开启测试服务器
  • Makefile 管理用
  • output 静态生成文件
  • peLicanconf.py 配置文件
  • publishconf.py 配置文件

基本操作

1
2
3
4
5
6
vim content/test.md
Title: 标题
Date:2019-01-04
Category： 类别
Tag: 标签 1,标签 2
内容
1
2
3
4
生成 html：make html
实时生成站点：make regenerate
看显示效果：make server
./develop_server.sh start
  • 生成的页面 push 到 github。

zeppelin

zeppelin：用于交互式数据分析的网页开源框架

Cookiecutter

cookiecutter

1
pip install cookiecutter
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
# 下载模板
cookiecutter https://github.com/pydanny/cookiecutter-django.git

# 配置信息
project_name [My Awesome Project]: myproject  # 项目名称
project_slug [myproject]: app01  # slug
description [Behold My Awesome Project!]: This is the first application!  # 项目描述
author_name [Daniel Roy Greenfeld]: yourname  # 作者
domain_name [example.com]: example.com  # 部署的域名
email [__jack__@example.com]: imooc@imooc.com  # 邮箱
version [0.1.0]:  # 版本号，默认为0.1.0
Select open_source_license:  # 选择项目License
1 - MIT
2 - BSD
3 - GPLv3
4 - Apache Software License 2.0
5 - Not open source
Choose from 1, 2, 3, 4, 5 (1, 2, 3, 4, 5) [1]: 5
timezone [UTC]: Asia/Shanghai  # Django settings中的TIME_ZONE
windows [n]: n # 是否是Windows环境
use_pycharm [n]: y  # 是否使用Pycharm开发
use_docker [n]: y  # 是否使用Docker容器
Select postgresql_version:  # 选择Postgres数据库版本，cookiecutter-django默认只支持Postgres
1 - 10.5
2 - 10.4
3 - 10.3
4 - 10.2
5 - 10.1
6 - 9.6
7 - 9.5
8 - 9.4
9 - 9.3
Choose from 1, 2, 3, 4, 5, 6, 7, 8, 9 (1, 2, 3, 4, 5, 6, 7, 8, 9) [1]: 1
Select js_task_runner:  # js运行方式
1 - None
2 - Gulp
Choose from 1, 2 (1, 2) [1]: 1
custom_bootstrap_compilation [n]: n  # 是否自定义bootstrap压缩
use_compressor [n]: n  # 是否使用压缩
use_celery [n]: n  # 是否使用celery，一个异步任务队列
use_mailhog [n]: n  # 是否使用mailhog，Django项目中发送邮件的，也可以使用Mailgun代替
use_sentry [n]: n  # 是否使用错误日志日志监控，sentry也是不错的开源python项目
use_whitenoise [n]: y  # 是否使用whitenoise
use_heroku [n]: n  # 是否使用heroku，heroku是国外著名的云服务厂商之一，提供PaaS
use_travisci [n]: n  # 是否使用travisci，类似于jekins，用于DevOps中的持续集成与发布
keep_local_envs_in_vcs [y]: y  # 对于本地环境变量使用版本控制
debug [n]: y  # 是否开启debug模式，settings中配置
 [SUCCESS]: Project initialized, keep up the good work!

pdoc

pdoc：基于Python的自动文档生成工具，可以生成python模块、类和函数的API文档。

基本使用

1
2
pip install pdoc

相关文章
给博主来一杯卡布奇诺