本杰明·本福特（Benjamin Bengfort）
科学的中心课程是，要理解复杂的问题（甚至是简单的问题），我们必须努力解放教条的思想，并保证发表，矛盾和试验的自由。
卡尔·萨根（Carl Sagan） ：《千亿万：千禧年边缘的生死思潮》
作为数据科学家，很容易陷入细节。 我们正忙于实现Python和R代码以从数据中提取有价值的见解，训练有效的机器学习模型或将分布式计算系统整合在一起。 这些任务中的许多任务，特别是与数据摄取或争用有关的任务，虽然很费时，但却是数据科学家日常工作的基础。 但是，我们经常忘记的是，我们不仅必须是数据工程师，而且还必须是数据科学知识体系的贡献者。
如果数据产品从数据中获取价值并生成更多数据作为回报，那么数据科学家将从先前发表的作品中获取其价值，并应生成更多出版物。 确实，机器学习无处不在的原因之一（请参阅与Stack on Overflow上的ML相关的许多带有Python标签的问题）是由于科学研究的精心撰写的博客文章和工具（例如Scikit-Learn）而得以快速实施的。各种算法。 尤其是Google，通过发布有关其方法论的系统论文来推动数据产品的增长，从而能够创建诸如Hadoop和Word2Vec之类的开源工具。
通过为软件和建模建立坚实的基础，我们能够更快地获得更大的结果。 探索，讨论，批评和实验都使我们能够通过利用数据社区的集体才智来拥有新思路，编写更好的代码并实现更好的系统。 在可预见的未来，出版对于使此数据科学领域的发展保持至关重要。
在学术界，“出版或灭亡”一词描述了通过出版物确立合法性的压力。 显然，我们并不想像作者一样坚持规则，但问题仍然是：“我们如何有效地将发布内容构建到我们的工作流中？”答案是通过标记语言 -可以添加到简单的简化标记中构建为发布布局或格式的文本文档。 例如，以下标记语言/平台内置于随附的可发布格式中：
- 降价→HTML
- iPython Notebook（JSON + Markdown）→交互式代码
- reStructuredText + Sphinx→Python文档，ReadTheDocs.org
- AsciiDoc→ePub，Mobi，DocBook，PDF
- 乳胶→PDF
标记语言的优点在于可以在同一软件版本库中与代码工作流内联管理它们。 Github在自动渲染Markdown文件方面更进一步！ 在本文中，我们将为您提供几种标记和发布样式的入门，以便您找到最适合您的工作流程和部署方法的内容。
降价促销
Markdown是我们将在本文中描述的最广泛使用的标记语言，它的简单性意味着它经常被选择用于各种领域和应用程序，而不仅仅是发布。 Markdown最初是由John Gruber创建的，是一种文本到HTML的处理器，其中使用了轻量级语法元素，而不是使用重量较大的HTML标签。 Markdown适用于为网络编写的人，而不是为网络设计的人，在某些CMS系统中，它只是您的编写方式，不需要精美的文本编辑器。
Markdown取得了特殊的增长，这要归功于Github，它具有Markdown的扩展版本，通常被称为“ Github-Flavored Markdown”。这种Markdown样式扩展了原始Markdown的基础，包括表格，语法突出显示和其他内联格式元素。 如果您在Github中创建Markdown文件，则在Web上查看文件时会自动呈现该文件，并且如果在目录中包含README.md ，则在浏览代码时该文件README.md现在目录内容下方。 Github Issues也有望出现在Markdown中，并通过复选框列表之类的工具进一步扩展。
Markdown用于许多应用程序，很难全部命名。 以下是一些可能对您的发布任务有用的选择。
- Jekyll允许您创建静态网站，这些网站是用Markdown编写的帖子和页面构建的。
- Github Pages允许您免费快速从Github存储库发布由Jekyll生成的静态站点。
- 第一天是一个简单的日记应用程序，可让您在Markdown中编写日记条目。
- iPython Notebook期望Markdown描述代码块。
- 堆栈溢出期望问题，答案和评论将以Markdown编写。
- MkDocs是用Markdown编写的软件文档工具，可以托管在ReadTheDocs.org上。
- GitBook是一个工具链，用于将用Markdown编写的书籍发布到网络上或作为eBook。
Markdown还提供各种各样的编辑器，浏览器插件，查看器和工具。 Sublime Text和Atom都支持Markdown和自动预览，以及大多数用于编码的文本编辑器。 Mou是Mac OSX的桌面Markdown编辑器，而iA Writer是iOS的Markdown的无干扰写作工具。 （请评论您最喜欢的Windows和Android工具）。 对于Chrome，像Markdown Here这样的扩展程序可以轻松地通过Markdown或Markdown Preview在Gmail中撰写电子邮件，以直接在浏览器中查看Markdown文档。
显然，Markdown拥有广泛的生态系统和多种用途。 如果您仍在为模板以外的其他任何东西编写HTML，那么您肯定在这一点上做错了！ 如果您有用户提交的文本，也值得为您自己的项目包括Markdown渲染（对于文本处理也非常有用）。
可以使用Python Markdown库（通常与Bleach库结合使用）清理Markdown，以清理不良的HTML和链接原始文本。 一个简单的演示如下：
首先使用pip安装markdown和bleach ：
$ pip install markdown漂白剂
然后创建一个markdown解析函数，如下所示：
进口 漂白剂
从 markdown 导入 markdown
def htmlize（文字）：
“”
该帮助器方法呈现Markdown，然后使用Bleach将其清理为
以及将文本中的所有链接转换为实际的定位标记。
“”
text = bleach.clean（text，strip = True） ＃通过剥离不良的HTML标签来清洁文本
text = markdown（text） ＃将markdown转换为HTML
text = bleach.linkify（text） ＃从文本中添加链接，并将nofollow添加到现有链接
返回文字
给定一个markdown文件test.md其内容如下：
＃我的降价文件
有关更多信息，请在[Google]（ http：//www.google.com ）上搜索。
_杂货清单： _
1 。 苹果
2 。 香蕉
3 。 橘子
如下代码：
>>> 以 open（'test.md'，'r'） 为 f：
... 打印 htmlize（f.read（））
将产生以下HTML输出：
我的降价文件
有关更多信息，请在<a href="http://www.google.com" rel="nofollow"> Google 上搜索 。
杂货清单：
苹果
香蕉
橘子
希望这个简短的示例还可以演示Markdown和其他标记语言如何使用轻量级标记结构将更简单的文本呈现到更大的发布框架中。 Markdown本身最常用于Web发布，因此，如果您需要编写HTML，那么这就是您的选择！
要了解有关Markdown语法的更多信息，请参阅Markdown基础。
iPython笔记本
iPython Notebook是一个基于Web的交互式环境，它将Python代码执行，文本（用Markdown标记），数学，图形和媒体组合到一个文档中。 iPython Notebook的动机纯属科学：您如何以可重复的方式展示或展示结果，以使其他人可以理解您所做的工作？ 通过创建一个交互式环境，使代码，图形，数学公式和RTF统一且可执行，iPython Notebook为无法理解或难以理解的代码提供了表示层。 尽管Markdown是iPython Notebook的重要组成部分，但由于它对数据科学界至关重要，因此值得特别提及。
iPython Notebook很有趣，因为它结合了表示层和标记层。 当作为服务器运行时，通常在本地，笔记本是可编辑的，可探索的（树视图将显示多个笔记本文件）和可执行文件-笔记本中用Python编写的任何代码都可以在后台使用交互式内核进行评估和运行。 LaTeX中编写的数学公式是使用MathJax呈现的。 为了增强这些笔记本的交付和可共享性，NBViewer允许您从Github存储库共享静态笔记本。
iPython Notebook附带了大多数科学发行的Python，例如Anaconda或Canopy，但是使用pip安装iPython也很容易：
$ pip安装ipython
iPython本身是增强的交互式Python Shell或REPL，它通过许多高级功能扩展了基本的Python REPL，主要是允许使用分离的两进程模型来启用笔记本。 该过程模型实质上将Python作为后台内核运行，该内核从客户端接收执行指令并将响应返回给客户端。
要启动iPython笔记本，请执行以下命令：
$ ipython笔记本
这将在http://127.0.0.1:8888启动本地服务器，并自动打开默认浏览器。 您将从“仪表盘视图”开始，该视图显示了当前工作目录中所有可用的笔记本。 在这里您可以创建新的笔记本并开始对其进行编辑。 笔记本作为.ipynb文件保存在本地目录中，该格式称为“ Jupyter”，它是简单的JSON，具有用于表示笔记本中每个单元格的特定结构。 Jupyter笔记本文件也是纯文本格式，因此可以通过Git和Github轻松还原。
要了解有关iPython Notebook的更多信息，请参阅iPython Notebook文档。
reStructuredText
reStructuredText是一种易于阅读的纯文本标记语法，专门设计用于Python文档字符串或生成Python文档。 实际上，reStructuredText解析器是Docutils的一个组件，Docutils是一种开放源代码文本处理系统，Sphinx使用它来生成智能且美观的软件文档，尤其是本机Python文档。
Python软件具有良好的文档记录已有很长的历史，尤其是因为应该包括电池。 而且文档是一个非常强大的电池！ PyPi是Python软件包索引，可确保第三方软件包提供文档，并且可以通过Python Hosted轻松在线托管该文档。 由于工具的易用性和普遍性，Python程序员以非常一致地记录代码而著称。 有时很难从第三方模块中分辨出标准库！
在如何开发高质量的Python代码中，我提到您应该使用Sphinx在顶层的docs目录中为您的应用程序和库生成文档。 在docs目录中生成reStructuredText文档非常简单：
$ mkdir文档
$ cd文档
$ sphinx-quickstart
快速入门实用程序将询问您许多问题来配置您的文档。 除了项目名称，作者和版本（您必须自己输入）之外，默认值还可以。 但是，我确实想更改一些内容：
...
> todo：编写可在构建（y / n）上显示或隐藏的“ todo”条目[n]：y
> 覆盖率：检查文档覆盖率（y / n）[n]：y
...
> mathjax：包括Math ，由MathJax在浏览器中呈现（y / n）[n]：y
类似于iPython Notebook，重新构造的文本可以呈现LaTeX语法数学公式。 该实用程序将为您创建一个Makefile。 要生成HTML文档，只需在docs目录中运行以下命令：
$使HTML
输出将建立在_build/html文件夹中，您可以在浏览器中打开index.html 。
虽然在Python Hosted上托管文档是一个不错的选择，但更好的选择可能是Read the Docs，该网站可让您创建，托管和浏览文档。 “阅读文档”的很大一部分是他们使用的样式表。 它比旧版本更具可读性。 此外，“阅读文档”使您可以连接Github存储库，以便每当您推送新代码（和新文档）时，它都会在网站上自动构建和更新。 阅读文档甚至可以为不同版本维护不同版本的文档。
请注意，即使您对学习reStructuredText的开销不感兴趣，也应该使用新发现的Markdown技能来确保“阅读文档”上托管的文档很好。 请参阅MkDocs以在Markdown中生成文档，Read the Docs将呈现该文档。
要了解有关reStructuredText语法的更多信息，请参见reStructuredText入门。
AsciiDoc
在编写更长的出版物时，您将需要一个功能更强大的工具，该工具与Markdown一样轻巧，但能够处理超越简单HTML的构造，例如交叉引用，章节编译或多文档构建链。 较长的出版物也应该从网络上移开，并且可以以电子书（ePub或Mobi格式）或印刷版面（例如PDF）呈现。 这些要求增加了更多的开销，但简化了大型媒体发布的工作流程。
为O’Reilly写作时，我发现我真的很喜欢在AsciiDoc中工作-一种轻量级的标记语法，与Markdown非常相似，后者可以呈现为HTML或DocBook。 DocBook非常重要，因为它可以被后处理成其他表示形式，例如HTML，PDF，EPUB，DVI，MOBI等，这使AsciiDoc不仅成为Web发布而且是印刷和书籍发布的有效工具。 大多数文本编辑器都有用于语法高亮显示的AsciiDoc语法，尤其是sublime-asciidoc和Atom AsciiDoc Preview，这使编写AsciiDoc就像Markdown一样容易。
AsciiDoctor是特定于AsciiDoc的工具链，用于从AsciiDoc构建书籍和网站。 该项目连接了各种AsciiDoc工具，并允许使用简单的命令行界面以及预览工具。 AsciiDoctor主要用于HTML和eBook格式，但是在撰写本文时，有一个PDF渲染器处于beta版。 O’Reilly的另一个有趣的项目是Atlas，这是一个用于按钮发布的系统，该系统使用Git存储库管理AsciiDoc，并将编辑构建过程，注释和自动编辑包装在Web平台中。 我不愿提及GitBook，尽管使用Markdown可以为出版较大的书籍提供类似的工具链。
编者注： GitBook确实支持AsciiDoc。
要了解有关AsciiDoc标记的更多信息，请参见AsciiDoc 101。
胶乳
如果您完成了STEM学位的任何研究生工作，那么您可能已经很熟悉LaTeX来撰写和发布文章，报告，会议和期刊论文以及书籍。 至少可以说，LaTeX不是一种简单的标记语言，但是它是有效的。 它能够处理几乎所有您可以使用的发布方案，包括（尤其是）使用文本标记语言正确渲染复杂的数学公式。 即使仅用于数学计算，大多数数据科学家仍然使用LaTeX，MathJax或Daum公式编辑器。
如果您要编写PDF或报告，我可以提供有关使用LaTeX的两个主要技巧。 首先考虑使用Overleaf或ShareLaTeX进行基于云的编辑，这使您可以像Google Docs一样协作和编辑LaTeX文档。 这两个系统都已经有许多类和样式表，因此您不必担心格式问题，而只需编写即可。 此外，它们汇总了LaTeX模板等其他工具，并为大多数文档类型提供了自己的模板。
但是，我个人最喜欢的工作流程是将Atom编辑器与LaTeX软件包和LaTeX语法一起使用。 使用Atom时，您将获得非常好的Git和Github集成-非常适合大型文档的协作。 如果您安装了TeX发行版（无论如何，您都需要在本地系统上执行此操作），则可以在Atom中自动生成文档并在PDF预览中查看它们。
在LaTeX的文本格式中可以找到学习LaTeX的完整教程。
结论
软件开发人员同意测试和文档对于成功创建和部署应用程序至关重要。 但是，尽管敏捷工作流旨在确保在软件开发生命周期中包含文档和测试，但是太多时候测试或文档被遗忘或遗忘。 在管理开发项目时，团队负责人需要确保文档和测试属于“完成的定义”的一部分。
同样，写入对于成功创建和部署数据产品至关重要，并且同样地任其发展或被遗忘。 通过发布我们的工作和思想，我们可以接受批评，这是检验思想和发现新思想的有效方法。 同样，通过明确共享我们的方法，我们可以使其他人更轻松地快速构建系统，而作为回报，可以编写教程来帮助我们更好地构建系统。 而且，如果我们将科学论文翻译成实用指南，也将有助于推动科学发展。
但是，不要对写作的细节感到困惑。 使用简单，轻便的标记语言在您的项目中包含文档。 使用版本控制系统与其他作者和您的团队进行协作，并使用免费工具使您的作品广泛可用。 所有这些都是由于轻量级标记语言的缘故，并且您越熟练地将代码写入工作流程中，就越容易分享您的想法。
有用的网址
这篇文章特别涉及大量链接，其中涉及许多工具和语言。 作为参考，这是我讨论的每种标记语言的首选指南：
- 降价基础
- iPython Notebook文档
- reStructuredText入门
- AsciiDoc 101
- 使用LaTeX进行文本格式化。
阅读书籍
- Arturo Herrero即时降价
- Cyrille Rossant撰写的《 IPython交互式计算和可视化食谱》
特别感谢Rebecca Bilbro对此文章的编辑和贡献。 没有她，这肯定会难以理解！
