You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This repo holds the content of the Web site http://sql-machine-learning.github.io, of which, https://sqlflow.org is an alias.
3
+
This repository holds the content of [SQLFlow.org](https://sql-machine-learning.github.io/). We rely on the [Github Pages](https://pages.github.com/) to convert Markdown files in this repo into HTML files. Github pages calls the converter [Jekyll](https://jekyllrb.com/docs/) , which churns through layout and other decorations. In addition, we use Jekyll to call [Just-the-Doc](https://pmarsceill.github.io/just-the-docs/) to generate the corresponding documents.
4
4
5
-
We rely on the [Github Pages](https://pages.github.com/) service to convert Markdown files in this repo into HTML files. Github Pages calls the converter [Jekyll](https://jekyllrb.com/docs/) , which churns through layout and other decorations. Besides, we configure Jekyll to call [Just-the-Doc](https://pmarsceill.github.io/just-the-docs/) for document generation.
6
-
7
-
## How to Contribute
8
-
9
-
When we make any change to this repo, we can run Jekyll locally to create a Web site for a quick preview of our change. If everything looks good, we can git-push our change to our fork repository, say, https://github.com/somebody/sql-machine-learning, and create a pull request. Reviewers could browse to https://somebody.github.io/sql-machine-learning.github.io/ for a preview.
10
-
11
-
## Walkthrough the Repository
5
+
## Repo Walkthrough
12
6
13
7
We see the following files and directories at the root of this repository:
14
8
@@ -19,31 +13,37 @@ We see the following files and directories at the root of this repository:
19
13
-`doc_index` holds template files of categories of documents generated by Jekyll and Just-the-Doc.
20
14
-`gohive`, `gomaxcompute`, `pysqlflow`, `sqlflow` are git-submodules to other repositories in the same organization. Jekyll and Just-the-Doc convert Markdown files in these git-submodules and listed in `/_config.yml` into the documentation. Also, `index.html` files in these subdirectories redirect URLs like https://sqlflow.org/gohive to https://github.com/sql-machine-learning/gohive
21
15
16
+
## Instructions for serving a local SQLFlow website
22
17
23
-
## Build and Serve Locally
18
+
To run SQLFlow website we need to install Jekyll and its dependencies. However, there are different versions of Jekyll, making it hard to reproduce runtime errors. Therefore, we recommend using dockerized Jekyll, which includes a specifici version (3.8) of Jekyll and the dependencies in the image. Note for Mac users, please install [Docker for Desktop](https://hub.docker.com/editions/community/docker-ce-desktop-mac); other tools like Docker Toolbox cannot expose Jekyll port in the local host.
24
19
25
-
To build the Web site locally, we may choose to install Jekyll. However, poeple might install different versions of Jekyll and dependencies, and it could be difficult to reproduce Web site build errors. So, we recommend running official Docker images of Jekyll, which includes a specified version of Jekyll and all its dependencies. The following command runs Jekyll 3.8 locally to build and serve the Web site.
20
+
**Step One**: Clone SQLFlow repo to your local machine. For potential contributors, please fork the repo and then make a clone.
**Step Two**: Update markdown files. Most of the document markdown files and redirect `index.html` files can be found in the adjacent repos like SQLFlow, GoHive, PySQLFlow. To include them into the website, we create git submodules like `/sqlflow` then point them to the right repo. If you are going through the instruction for the first time, please use below command to include the markdown files before running Jekyll serve. Whenever there are updates to markdown file in other repo, please run the command again without --init to update the content. Otherwise, the updated content won't show up.
27
+
28
+
```bash
29
+
git submodule update --init --recursive --remote
30
+
```
31
+
32
+
**Step Three**: Fire up docker run under the repo root. Note the command will pull the image from the remote automatically. Also, make sure to replace `b90ffea2` with your personal access token. It takes a few seconds to generate the token by following [this document](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line). Now you can access SQLFlow.org from http://localhost:4000 with exact the same content.
33
+
34
+
```bash
29
35
cd sql-machine-learning.github.io
30
36
docker run --rm -it \
31
-
-v $PWD:/srv/kyll \
37
+
-v $PWD:/srv/jekyll \
32
38
-e JEKYLL_GITHUB_TOKEN=b90ffea2 \
33
39
-p 4000:4000 \
34
40
jekyll/jekyll:3.8 \
35
-
jekyll serve
41
+
jekyll serve --incremental
36
42
```
37
43
38
-
Please make sure to replace `b90ffea2` by your Github personal access token. It takes you a few seconds to create one by following [this document](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line).
44
+
## Jekyll Pages, Documents, and Redirects
39
45
40
-
For macOS users, please install [Docker for Desktop](https://hub.docker.com/editions/community/docker-ce-desktop-mac); other implementations like Docker Toolbox cannot expose Jekyll port to your macOS host.
41
-
42
-
Now, browse to http://localhost:4000 for the Web site.
43
-
44
-
## Pages, Documents, and Redirects
45
-
46
-
The generated Web site serves the following kinds of content.
46
+
The generated website serves the four kinds of contents below:
@@ -67,39 +67,33 @@ The generated Web site serves the following kinds of content.
67
67
68
68
Jekyll allows document authors to specify the layout template by adding a [front matter](https://jekyllrb.com/docs/front-matter/) in their document Markdown files. However, most document authors are developers who don't know anything about the front matter and follow the plain Markdown syntax. So, in `/_config.yml` we write the following snippet
69
69
70
-
```yaml
71
-
# in _config.yml, using defaults to set default value of md files
72
-
defaults:
73
-
- scope:
74
-
path: "sqlflow"
75
-
values:
76
-
layout: "doc"
77
-
nav_exclude: true # hide all files from nav
78
-
grand_parent: Document
79
-
```
70
+
```yaml
71
+
# in _config.yml, using defaults to set default value of md files
72
+
defaults:
73
+
- scope:
74
+
path: "sqlflow"
75
+
values:
76
+
layout: "doc"
77
+
nav_exclude: true # hide all files from nav
78
+
grand_parent: Document
79
+
```
80
80
81
-
where `layout: doc"` specifies the default layout template file to be `/_layouts/doc.md`.
81
+
where `layout: doc"` specifies the default layout template file to be `/_layouts/doc.md`.
82
82
83
-
Another essential role of `/_config.yml` is to pick some Markdown files as document page source files.
83
+
Another essential role of `/_config.yml` is to pick some Markdown files as document page source files.
84
84
85
85
86
86
1. The Navigation Bar
87
87
88
88
In `_data/navigation.yml`, we define the navigation bar on the homepage. Currently, there are three links there. If we want more than three, we would need to edit the style of `_layout/index.html`.
89
89
90
90
91
-
## Git-submodules
92
-
93
-
Most of the document Markdown files and redirect `index.html` files are in repositories like https://github.com/sql-machine-learning/sqlflow. To interleave them into this Web site, we create git-submodules like `/sqlflow` pointing to the repository. After editing files in these repositories, please remember to update the git-submodules to point to the most recent version.
94
-
95
-
```bash
96
-
git submodule update --init --recursive --remote
97
-
```
91
+
## How to Contribute
98
92
93
+
When we make change to this repo, we can run Jekyll locally to create a Web site for a quick preview of our change. If everything looks good, we can git-push our change to our fork repository, say, https://github.com/somebody/sql-machine-learning, and create a pull request. Reviewers could go to https://somebody.github.io/sql-machine-learning.github.io/ for a preview. (To enable the preview of your fork, you need to change the settings of your fork as described [here](https://github.com/sql-machine-learning/sql-machine-learning.github.io/issues/46)).
99
94
100
-
## Troubleshooting
95
+
## Trouble Shooting
101
96
102
97
- Jekyll liquid syntax error
103
98
104
99
Jekyll allows Markdown file authors to use the liquid braces `{{}}` to specify the front matter. To avoid ambiguity, when we write double curly braces in our Markdown files, we must wrap them up into `{% raw %}` and `{% endraw %}` or we can try just don't use double curly braces.
0 commit comments