Site Instructions

Base Technique

This project is based on Jekyll and Just The Docs

Doc:

• Jekyll
• Just the Doc

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
├── docs ----------| Generating Destination
├── 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
# Start serving through localhost:4000

$ bundle exec jekyll build
# build site files into docs

Site development

There are two kinds of page in this project now, Doc and Page

Page

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

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
  - 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