生成并托管您的iOS文档

作为程序员，每个人都告诉您要负责并编写代码。 它为您正在编写的代码提供了上下文，并使您更容易了解正在发生的事情。

记录我们的代码很棒，但是如果我们可以直接从代码中生成并托管漂亮的文档，该怎么办？ 通过正确的设置，我们甚至可以搜索文档。 请看下面的样本文档页面：

BackgroundColorState枚举参考
可以通过用下一个后台状态覆盖状态来更新状态。 jgsamudio.github.io

有什么计划？

在这篇文章中，我们将使用Jazzy为我们的文档生成一个网站。 然后学习如何在Github Pages上托管它，最后确保它与Travis CI保持最新。

如果您不熟悉CI或尚未为项目设置Travis CI，请查看此博客以获取一些见解：“如何为CI和iOS Project自动化CI”

产生文件

开发人员可以尽可能快地编写文档，但速度却已过时。 我们需要一种生成文档的方法，这样就可以避免在很多地方都必须更新文档。

Jazzy是一个命令行应用程序，可以将Swift和Objective-C文档生成到html网站中。

爵士安装

在安装Jazzy之前，我们需要安装“ Xcode命令行工具”。 您可以运行以下命令来安装它们： xcode-select —-install 。 安装完成后，您可以运行[sudo] gem install jazzy来安装Jazzy。

成功安装后，我们可以运行Jazzy并使用不同的文档选项对其进行自定义。

 爵士乐 
  --min-acl内部\ 
  --no-hide-documentation-coverage \ 
  -主题全角\ 
  --output ./docs \ 
  --documentation =。/ *。md 

1. min-acl内部

min-acl属性控制生成的最低访问级别。 由于我们正在记录所有公共函数和变量，因此将其设置为internal 。 私有和Fileprivate函数和变量将不在生成的文档中。 要记录所有内容，必须将min-acl设置为private 。

2.无隐藏文档覆盖

在文档中启用文档百分比计数器。

3.主题全角

使用搜索栏更改为自定义主题。

4.输出./docs

生成文档的输出路径。 设置为./docs会将所有生成的文件放在项目根目录下的docs文件夹中。

5.文档= ./*md

在生成的文档中添加一个部分，并带有指向自述文件的链接。 我们可以将其用作文档的主页。

创建Makefile以使生活更轻松

无需每次都编写Jazzy命令，我们可以将其封装在“ Makefile”中。

 说明文件： 
  @爵士乐\ 
  --min-acl内部\ 
  --no-hide-documentation-coverage \ 
  -主题全角\ 
  --output ./docs \ 
  --documentation =。/ *。md 
  @rm -rf ./build 

通过使用喜欢的文本编辑器，您可以创建一个新文件并将其命名为“ Makefile”。 创建完成后，您可以复制并粘贴上面的代码以定义新的“文档”命令。 现在，从终端，我们可以通过运行make documentation来生成我们的make documentation 。

查看生成的文档

使用上述配置运行Jazzy将在项目的根目录中创建一个docs文件夹。 该文件夹中将包含查看您的文档所需的HTML资源。

双击index.html文件将在默认浏览器上打开生成文档的本地实例。