【发布时间】：2018-02-27 11:31:38
【问题描述】：
我完成了我的第一份计算草稿，想知道如何最有效地将代码传达给非 Python 用户。我在考虑一个 HTML 或 PDF 文件（可能是 jupyter notebook 样式），它允许整齐地显示代码及其渲染输出，以及一些文本来彻底解释每个步骤中所做的事情。我看到 Markdown 似乎是为此目的的一个包，但在我阅读包特定语法之前，我想知道是否有更简单的方法来解决它。
【问题讨论】：
-
我在创建和展示 Jupyter 笔记本以向非程序员传达代码的意图和流程方面取得了不错的成绩。
-
@cco 我认为这可行，但我希望能够向他们发送不需要任何特定知识的文件，而不是期望他们学习 Jupyter 笔记本的基础知识
-
恕我直言，这有点不清楚。你想解释实际的代码、算法还是程序在做什么？读者是另一个碰巧不了解 Python 的程序员，还是“代码文盲”？对于几行短线，笔记本或类似的东西可能会起作用，但对于较大的项目，您可能会考虑使用 UML 代替，从实际代码中抽象出来。同样，如果你想展示一个算法，考虑使用伪代码，或者只是命名算法，如果它是一些标准的。
-
@tobias_k 我想轻松地交流代码和算法。我认为他们可能有一些 Stata 或 R 知识，但我更愿意让它尽可能简单，并假设他们没有任何编程知识。到目前为止，它不是一个长脚本（大约 100 行）。鉴于我的主管是合着者，我不想过多地使用伪代码或抽象，因为毕竟他们需要最终理解所做的事情并同意它。感谢 UML 的提示
-
您可以将笔记本导出为 HTML 或 PDF 以进行分发；我在 Windows 环境中工作，因此对于一个类似大小的项目，我将其导出为 HTML 并将其导入 Word 以进行分发。