为非程序员记录Python脚本

时间:2010-10-13 21:08:05

标签: python documentation-generation

我们目前正在寻找方法来帮助sysadmin小组的非编程成员熟悉用于日常系统管理员任务的Python脚本。

是否有人有任何建议的文档工具或最佳实践,我们可能会发现这些工具或最佳实践可用于此目的?

编辑以解决S.Lott的评论:

首先,我对我最初的问题过于简短表示歉意。我的主要目标是确保某人,即使是非程序员,如果我当天不在或离开组织,也能轻松排除我的脚本故障。

我正在寻找的是在系统管理员团队等技术小组中具有“脚本编码器”角色的其他人所使用的做法。例如,在我开始编写任务脚本的过程之前,我已经养成了在我们的共享wiki中首先写一篇文章的习惯,详细解释每一步。然后我将我的Python脚本基于文章 - 将其用作伪代码。

我正在寻找的各种事物的其他例子:

  • 使用Sphinx等工具提供易于理解的文档

  • 在投入生产之前进行小组讨论以讨论代码

  • 允许小组成员首先手动完成这个过程(我们通常采用这条路线,但也许我们应该让它更常见)

或者,同样有价值的,如果不是更有价值,例如:

  • 发现沉重的评论是浪费时间,因为逻辑流程对于非程序员来说仍然是陌生的

  • 倾向于使用pexpect因为使用高级模块时丢失了详细信息

以上只是我想到的事情的例子。希望这澄清了这个问题!一如既往,感谢SO'ers。

2 个答案:

答案 0 :(得分:2)

有一本关于这个主题的书 - “用于Unix和Linux系统管理的Python”。

有关开发人员的文章可能会为您提供您可能想要遵循的风格。

几乎任何一个人,无论他将如何应用它,都希望研究语言本身的基础知识。除了与标准python发行版一起发布的教程之外,Web上有一个很好的入门者。

答案 1 :(得分:2)

我发现使用argparse作为脚本调用解析/路由的基础往往会产生一个像样的第一行文档。如果按预期使用,您的系统管理员可以运行some_script --help以获取脚本用途的描述及其选项的摘要。

将解析器构建代码使用的文档源链接到代码中的函数和类的实际文档字符串以及脚本本身的文档字符串可能相当简单。这取决于脚本的复杂程度,但这通常是获取足够文档的低成本方法。