如何将Databricks Notebook转为.py文件适配mkdocs文档构建？

一、编程实现Notebook转带标记的Python文件 #

针对你给出的含%sql等魔法命令的纯文本Notebook格式，可通过Python脚本自动完成转换——核心逻辑是给魔法命令块添加# MAGIC前缀，块之间用# COMMAND ----------分隔，具体代码如下：

def convert_notebook_to_py(input_file, output_file):
    with open(input_file, 'r', encoding='utf-8') as f:
        content = f.read()
    
    # 按空行分割内容块，过滤空块
    blocks = [block.strip() for block in content.split('\n\n') if block.strip()]
    converted_content = ['# Databricks notebook source\n']
    
    for idx, block in enumerate(blocks):
        # 判断是否为魔法命令块（以%开头）
        if block.startswith('%'):
            # 给块内每一行添加# MAGIC前缀，空行保留# MAGIC标记
            magic_lines = [f'# MAGIC {line}' if line.strip() else '# MAGIC' for line in block.split('\n')]
            converted_content.append('\n'.join(magic_lines))
        else:
            # 普通Python代码直接保留原格式
            converted_content.append(block)
        
        # 块之间添加分隔符（最后一个块不加）
        if idx != len(blocks) - 1:
            converted_content.append('\n\n# COMMAND ----------\n')
    
    # 写入输出文件
    with open(output_file, 'w', encoding='utf-8') as f:
        f.write('\n'.join(converted_content))

# 使用示例：替换为你的实际文件路径
convert_notebook_to_py('workspace_notebook.txt', 'output.py')

这个脚本可完美处理你提供的示例输入，支持多段魔法命令与普通代码混合的场景。

二、其他替代方案 #

除了手动转PY的临时方案，还有更高效的解决思路：

• 使用MkDocs专属插件：直接采用mkdocs-jupyter插件，它能直接解析Jupyter Notebook（.ipynb）文件，将代码、输出、Markdown内容渲染为MkDocs支持的文档格式，无需手动转换。仅需在mkdocs.yml中配置插件即可，省去中间转文件的步骤。

• 自动化构建流程：若坚持用转PY的方案，可将转换、构建、清理步骤集成到自动化脚本中。例如编写Shell脚本：

#!/bin/bash
# 批量转换Notebook文件为py格式
for nb in *.txt; do
    python convert_notebook_to_py "$nb" "${nb%.txt}.py"
done
# 执行MkDocs构建
mkdocs build
# 清理生成的py文件
rm -f *.py

每次构建只需运行该脚本，无需手动操作。

• 用官方工具导出：若你的Notebook属于Databricks环境，可使用Databricks CLI直接导出为带标记的Python文件，命令如下：

databricks workspace export /your/workspace/notebook/path output.py --format source

官方工具导出的格式完全符合需求，无需自行编写转换逻辑。

内容的提问来源于stack exchange，提问作者Error_2646