Skip to content

Site Instructions

Jump to bottom
weiguoz edited this page Jul 16, 2019 · 8 revisions

Site Generation

We use the following tools to generate content in this repo into our web site https://sqlflow.org:

Project Structure

.
├── Gemfile -------|
├── Gemfile.lock --| Ruby dependences
├── README.md
├── _config.yml ---| Jekyll Config
├── _data ---------| Global Render Data （now not using）
├── _layouts ------| Render Layout Template
├── assets --------| Source Files
├── carousel.css
├── dist
├── doc_index -----| Doc Index pages
├── favicon.ico ---| Site favicon 
├── gohive
├── index.md ------| Index Config
├── pages
├── pysqlflow
└── sqlflow -------| Submodule from sqlflow/develop

How to use

Make sure you installed Ruby

$ gem install bundler
# Installs the Bundler gem
$ bundle install
# Installs dependence through bundler
$ bundle exec jekyll serve --incremental
# Start serving through localhost:4000
# What you saw here will be what the website will be

Site development

There are two kinds of pages in this project now: doc and page

Page

Pages are not using Just the Docs theme. It's a custom page.

Site index

It's rendered by index.md and _layout/index.html

title: "SQLFlow: Bridging Data and AI" # Website Title
layout: index
nav_exclude: true
permalink: "/"
main: "SQLFlow" # Index Page Colored Title
subtitle: "Extends SQL to support AI. Extract knowledge from Data." 
intro: "Currently support MySQL and TensorFlow. Expanding to Apache Hive, Alibaba ODPS, and PyTorch"
features: # feature below the instruction
  - title: 'Easy to Learn'
    content: 'Manipulate data and running AI with SQL'
  - title: 'Work with Many Database Management Systems'
    content: 'MySQL, Hive, Alibaba ODPS, Oracle and you name it!'
  - title: 'Support Many Machine Learning Toolkits'
    content: 'TensorFlow, PyTorch, xgboost, and more!'

when you changed the link of the index menu, you need to change it through _layout/index.html

Redirect index.html

Some of index.html just for redirecting page or redirecting go import usage, they will just be copied into the destination.

Docs

Docs are using just the doc theme, and usually, they are from SQLFlow's markdown files.

They are all using _layout/doc.md layout, and by default, they are nav excluded.

And we are using the config to implement it

# in `_config.yml`, using defaults to set default value of md files
defaults:
  - scope:
      path: "sqlflow"
    values:
      layout: "doc"
      nav_exclude: true # hide all files from nav
      grand_parent: Document
      prefix: '/sqlflow/' # In order to generate correct links, we add this key to replace '/' in documents' links
  - scope:
      path: "sqlflow/doc/quickstart.md"
    values:
      nav_exclude: false # excluded file we need to show in nav
      parent: Document # determine it's parent
      nav_order: 1 # order them in nav
# all of the value after will overwrite values before

And every parent can be find in doc_index directory

Config

Navigation

In _data/navigation.yml you could find it If links more than 3, you may change the style of _layout/index.html

main:
  - title: "Installation" # title
    url: sqlflow/doc/installation # href
  - title: "Documents"
    url: doc_index/doc
  - title: "GitHub"
    url: https://github.com/sql-machine-learning

Update

This project now will update it automatically, so all we need to update is the files we need.

# update submodule --init is for the first time
$ git submodule update --init --recursive --remote

Then push changes, waiting for GitHub pages changing (About 1-5 minutes, if there's no error)

Common problem

  • jekyll liquid syntax error

    Usually with {{}} in the doc will cause this, wrap them in {% raw %} and {% endraw %} or delete them

Clone this wiki locally