aip.dev和分支的静态网站生成器。
项目描述
aip.dev静态网站生成器
这是aip.dev及其分支的网站生成器。它将git仓库中的AIP文件输出为静态网站。
为什么？
我们不是很喜欢自己开发工具，当市面上有现成的替代品时。然而，AIP项目已经足够成熟，值得这样做。
GitHub Pages通常会自动使用Jekyll构建文档，但随着AIP系统的增长，我们开始达到Jekyll能够处理的极限，其他现成的生成器也有类似的问题
- AIP采用通过分支和合并处理，自上而下的配置文件会导致重复的合并冲突。
- 我们的分组和列表逻辑变得复杂，必须使用复杂且容易出错的Liquid模板来维护。
- Jekyll可扩展，但GitHub需要特定的Jekyll插件，这意味着我们不能为计划中的功能（例如分页代码示例）使用现成的解决方案。
- 缺乏有意义的构建CI导致失败。
- 与开发环境一起工作（真的很）慢。
使用自定义生成器，我们解锁了一些额外的优势。
- 我们可以使用新文件中的模板扩展来覆盖AIP的部分，而不是修改现有文件。
- 我们可以为公司之间常见的偏差（例如案例系统）提供有用的抽象，从而最大限度地减少对分叉AIP的需求。
- 在需要的地方，我们可以自定义Markdown解析（制表符、热链接等）。
它是如何工作的？
这基本上分为三个部分
- Python代码（
aip_site/）- 大部分代码是模型（
aip_site/models/），它们代表了AIP站点的根本概念。这些被汇总成一个称为Site的单例对象，它被用于任何地方。所有模型都是发送到模板的数据类。 - 还有一个发布类（
aip_site/publisher.py），它能够吞咽AIP的仓库并构建一个静态网站。 - 还有一些服务器代码（
aip_site/server.py），它可以运行开发服务器。 - 所有剩余的文件都是薄支持代码，以避免在上面的文件中或之间重复。
- 大部分代码是模型（
- 模板（
support/templates/）是包含（主要）HTML的Jinja2模板，这些HTML构成了网站的布局。 - 资产（
support/assets/和support/scss/）是其他静态文件。SCSS在发布时会自动编译成CSS。
在模型中，有三个模型特别重要
- Site: 提供对所有范围、AIP和静态页面的访问的单例。这个作为
site变量发送到每个模板。 - AIP: 表示单个AIP的表示，包括内容和元数据。这个作为
aip变量发送到AIP渲染模板。 - Scope: 应用于特定范围的一组AIP。特殊的“通用”范围是“根”组。这个作为
scope变量发送到AIP列表模板。
模板是templates/目录中的jinja2文件。
注意：我们使用“严格未定义”来运行Jinja，因此模板中引用未定义的变量是一个硬错误，而不是空字符串。
入口点
应用程序有两个入口点。程序publisher（aip_site/publisher.py）是迭代相关目录、渲染HTML文件并将它们写入磁盘的程序。程序app（aip_site/server.py）是一个轻量级的Flask应用程序，提供开发服务器。
这些入口点通过CLI文件（aip_site/cli.py）路由；当使用pip安装此应用程序时，它使aip-site-gen（发布者）和aip-site-serve（服务器）命令可用。
扩展
此网站生成器包括一个基本的AIP扩展系统。当处理作为纯Markdown文件的AIP时，它将任何Markdown（级别2或3）标题转换为块。因此...
## Foo bar baz
Lorem ipsum dolor set amet
变为...
{% block foo_bar_baz %}
## Foo bar baz
Lorem ipsum dolor set amet
{% endblock %}
这允许覆盖模板扩展原始模板并覆盖部分
{% extends aip.templates.generic %}
{% block foo_bar_baz %}
## My mo-betta foo bar baz
Lorem ipsum dolor set something-not-amet
{% endblock %}
开发者设置
如果您想为此项目做出贡献，您将需要一个可以快速更改代码并看到您更改结果的设置。以下是一个快速设置本地开发环境的方法，这样您就可以在不重新安装命令行脚本的情况下进行代码开发。
依赖项
您需要venv。在Linux上，使用以下命令安装：
sudo apt-get install python3-venv
运行开发环境
- 检出源代码
$ mkdir src
$ cd src
$ git clone https://github.com/aip-dev/site-generator.git
- 设置Python虚拟环境
$ python3 -m venv .venv
$ source .venv/bin/activate
- 使用可编辑选项进行PIP安装
$ pip install --editable .
- 服务aip.dev网站
$ aip-site-serve /path/to/aip/data/on/your/system
