diff --git a/docs/documentation/cn/administrator-guide/http-actions/index.rst b/docs/documentation/cn/administrator-guide/http-actions/index.rst new file mode 100644 index 0000000000..268e99b5a8 --- /dev/null +++ b/docs/documentation/cn/administrator-guide/http-actions/index.rst @@ -0,0 +1,9 @@ +============= +HTTP API +============= + +.. toctree:: + :maxdepth: 1 + :glob: + + * diff --git a/docs/documentation/cn/administrator-guide/index.rst b/docs/documentation/cn/administrator-guide/index.rst new file mode 100644 index 0000000000..a7841a121b --- /dev/null +++ b/docs/documentation/cn/administrator-guide/index.rst @@ -0,0 +1,16 @@ +============= +操作手册 +============= + +.. toctree:: + :maxdepth: 1 + :glob: + + * + +.. toctree:: + :hidden: + + http-actions/index + load-data/index + operation/index diff --git a/docs/documentation/cn/administrator-guide/load-data/index.rst b/docs/documentation/cn/administrator-guide/load-data/index.rst new file mode 100644 index 0000000000..fe908259db --- /dev/null +++ b/docs/documentation/cn/administrator-guide/load-data/index.rst @@ -0,0 +1,9 @@ +============= +数据导入 +============= + +.. toctree:: + :maxdepth: 2 + :glob: + + * diff --git a/docs/documentation/cn/administrator-guide/load-data/routine-load-manual.md b/docs/documentation/cn/administrator-guide/load-data/routine-load-manual.md index 98b440ac01..90c2ece9fd 100644 --- a/docs/documentation/cn/administrator-guide/load-data/routine-load-manual.md +++ b/docs/documentation/cn/administrator-guide/load-data/routine-load-manual.md @@ -63,7 +63,7 @@ FE 中的 JobScheduler 根据汇报结果，继续生成后续新的 Task，或 ### 创建例行导入任务 -创建例行导入任务的的详细语法可以参照 [这里]()。或者连接到 Doris 后，执行 `HELP CREATE ROUTINE LOAD;` 查看语法帮助。这里主要详细介绍，创建作业时的注意事项。 +创建例行导入任务的的详细语法可以连接到 Doris 后，执行 `HELP CREATE ROUTINE LOAD;` 查看语法帮助。这里主要详细介绍，创建作业时的注意事项。 * columns_mapping diff --git a/docs/documentation/cn/administrator-guide/operation/index.rst b/docs/documentation/cn/administrator-guide/operation/index.rst new file mode 100644 index 0000000000..978ac3d83f --- /dev/null +++ b/docs/documentation/cn/administrator-guide/operation/index.rst @@ -0,0 +1,9 @@ +============= +运维操作 +============= + +.. toctree:: + :maxdepth: 2 + :glob: + + * diff --git a/docs/documentation/cn/extending-doris/index.rst b/docs/documentation/cn/extending-doris/index.rst new file mode 100644 index 0000000000..4fda2a01df --- /dev/null +++ b/docs/documentation/cn/extending-doris/index.rst @@ -0,0 +1,8 @@ +=========== +扩展功能 +=========== + +.. toctree:: + :glob: + + * diff --git a/docs/documentation/cn/internal/index.rst b/docs/documentation/cn/internal/index.rst new file mode 100644 index 0000000000..2d2aee33b2 --- /dev/null +++ b/docs/documentation/cn/internal/index.rst @@ -0,0 +1,8 @@ +=========== +设计文档 +=========== + +.. toctree:: + :glob: + + * diff --git a/docs/documentation/cn/sql-reference/index.rst b/docs/documentation/cn/sql-reference/index.rst new file mode 100644 index 0000000000..c30bebbc01 --- /dev/null +++ b/docs/documentation/cn/sql-reference/index.rst @@ -0,0 +1,9 @@ +=========== +SQL 手册 +=========== + +.. toctree:: + :hidden: + + sql-functions/index + sql-statements/index diff --git a/docs/documentation/cn/sql-reference/sql-functions/date-time-functions/index.rst b/docs/documentation/cn/sql-reference/sql-functions/date-time-functions/index.rst new file mode 100644 index 0000000000..9841d7ea1d --- /dev/null +++ b/docs/documentation/cn/sql-reference/sql-functions/date-time-functions/index.rst @@ -0,0 +1,8 @@ +============= +日期函数 +============= + +.. toctree:: + :glob: + + * diff --git a/docs/documentation/cn/sql-reference/sql-functions/index.rst b/docs/documentation/cn/sql-reference/sql-functions/index.rst new file mode 100644 index 0000000000..b9547de896 --- /dev/null +++ b/docs/documentation/cn/sql-reference/sql-functions/index.rst @@ -0,0 +1,15 @@ +=========== +SQL 函数 +=========== + +.. toctree:: + :glob: + + * + +.. toctree:: + :hidden: + + date-time-functions/index + spatial-functions/index + string-functions/index diff --git a/docs/documentation/cn/sql-reference/sql-functions/spatial-functions/index.rst b/docs/documentation/cn/sql-reference/sql-functions/spatial-functions/index.rst new file mode 100644 index 0000000000..f09712d02b --- /dev/null +++ b/docs/documentation/cn/sql-reference/sql-functions/spatial-functions/index.rst @@ -0,0 +1,8 @@ +============= +地理位置函数 +============= + +.. toctree:: + :glob: + + * diff --git a/docs/documentation/cn/sql-reference/sql-functions/string-functions/index.rst b/docs/documentation/cn/sql-reference/sql-functions/string-functions/index.rst new file mode 100644 index 0000000000..7d372f8a93 --- /dev/null +++ b/docs/documentation/cn/sql-reference/sql-functions/string-functions/index.rst @@ -0,0 +1,8 @@ +============= +字符串函数 +============= + +.. toctree:: + :glob: + + * diff --git a/docs/documentation/cn/sql-reference/sql-statements/index.rst b/docs/documentation/cn/sql-reference/sql-statements/index.rst new file mode 100644 index 0000000000..4f3490142c --- /dev/null +++ b/docs/documentation/cn/sql-reference/sql-statements/index.rst @@ -0,0 +1,8 @@ +============ +DDL 语句 +============ + +.. toctree:: + :glob: + + * diff --git a/docs/readme.md b/docs/readme.md index 3bb894ecf0..34d0ee743e 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -30,7 +30,8 @@ Documentations will be written once, and will be converted to other format accor > `docs/documentation`: Root directory for documentation. And for different languages, there is a root directory for it. For example, `docs/documentation/cn` is the Chinese documentation's root directory. > `docs/scripts`: Place of `Doc Builder`. ->  `docs/resources`: Resources that are referenced in documentation, such as pictures. +> `docs/resources`: Resources that are referenced in documentation, such as pictures. +> `docs/website`: A website for documentations built with [Sphinx](http://www.sphinx-doc.org) using a theme provided by [Read-the-Docs](https://readthedocs.org/). ## Constraints @@ -41,7 +42,7 @@ Documentations will be written once, and will be converted to other format accor 3. A directory corresponds to a title, and readme.md in this directory is its content. Other documents in this directory is its sub-sections. 4. For manual like section, such as function description, there should be `Description`, `Syntax`, `Examples` section in documents. -## level directories +## Level Directories 1. doris-concepts 2. installing @@ -50,3 +51,24 @@ Documentations will be written once, and will be converted to other format accor 5. sql-references 6. best-practices 7. internals + +Each directory, or its sub directories should contain a file `index.rst`, for constructing the navibar of the website. For example: + +``` +documentation/ +└── cn + ├── administrator-guide + │   ├── index.rst + │   ├── http-actions + │   │   └── index.rst + │   ├── load-data + │   │   ├── index.rst + │   ├── operation + │   │   ├── index.rst + ├── extending-doris + │   ├── index.rst + └── sql-reference + ├── index.rst + │   ├── date-time-functions + │   │   ├── index.rst +``` diff --git a/docs/website/Makefile b/docs/website/Makefile new file mode 100644 index 0000000000..69fe55ecfa --- /dev/null +++ b/docs/website/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/website/README.md b/docs/website/README.md new file mode 100644 index 0000000000..294684d2ca --- /dev/null +++ b/docs/website/README.md @@ -0,0 +1,40 @@ +# Build the website for Doris documentations + +## Prerequisites + +1. Install PiPy (If not installed) + + ``` + curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py + python get-pip.py + ``` + +2. Install sphinx and other dependencies + + ``` + pip install sphinx # Sphinx main program + pip install recommonmark # Sphinx markdown extension + pip install sphinx_rtd_theme # Sphinx Read-the-Docs theme + pip install sphinx-markdown-tables # Sphinx markdown table render extension + ``` + +## Build the website + +``` +sh build_site.sh +``` + +## Start web server + +``` +cd build/html/ +nohup python -m SimpleHTTPServer & +``` + +You can start any web server you like. + +## Browse website + +``` +http://localhost:8000/ +``` diff --git a/docs/website/build_site.sh b/docs/website/build_site.sh new file mode 100644 index 0000000000..efbca852a0 --- /dev/null +++ b/docs/website/build_site.sh @@ -0,0 +1,89 @@ +#!/usr/bin/env bash +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +set -eo pipefail + +CUR=`dirname "$0"` +CUR=`cd "$CUR"; pwd` + +export DORIS_HOME=${CUR}/../../ + +# Check args +usage() { + echo " +Usage: $0 + Optional options: + --cn build Chinese Documentation + --en build English Documentation + " + exit 1 +} + +OPTS=$(getopt \ + -n $0 \ + -o '' \ + -l 'cn' \ + -l 'en' \ + -l 'help' \ + -- "$@") + +if [ $? != 0 ] ; then + usage +fi + +eval set -- "$OPTS" + +BUILD_CN= +BUILD_EN= +HELP=0 +if [ $# == 1 ] ; then + # default + BUILD_CN=1 + BUILD_EN=0 +else + BUILD_CN=0 + BUILD_EN=0 + while true; do + case "$1" in + --cn) BUILD_CN=1 ; shift ;; + --en) BUILD_EN=1 ; shift ;; + --help) HELP=1; shift ;; + --) shift ; break ;; + *) ehco "Internal error" ; exit 1 ;; + esac + done +fi + +if [[ ${HELP} -eq 1 ]]; then + usage + exit +fi + + +if [ ${BUILD_CN} -eq 1 ] ; then + rm -rf ${CUR}/source/Docs/* + rm -rf ${CUR}/source/resources/ + cp -r ${DORIS_HOME}/docs/documentation/cn/ ${CUR}/source/Docs/ + cp -r ${DORIS_HOME}/docs/resources/ ${CUR}/source/ + + make clean && make html +elif [ ${BUILD_EN} -eq 1 ] ; then + echo "not implemented yet" + exit 1 +fi + diff --git a/docs/website/source/conf.py b/docs/website/source/conf.py new file mode 100644 index 0000000000..12cc83d7d6 --- /dev/null +++ b/docs/website/source/conf.py @@ -0,0 +1,187 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + +#import t3SphinxThemeRtd + +# -- Project information ----------------------------------------------------- + +project = u'Doris Documentations' +copyright = u'2019, Apache Doris(Incubating)' +author = u'Apache Doris(Incubating)' + +# The short X.Y version +version = u'0.1.0' +# The full version, including alpha/beta/rc tags +release = u'0.1.0' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'recommonmark', + 'sphinx_markdown_tables' +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +# source_suffix = '.rst' +source_suffix = { + '.rst': 'restructuredtext', + '.txt': 'markdown', + '.md': 'markdown', +} + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" +#html_theme = "t3SphinxThemeRtd" +#html_theme_path = [t3SphinxThemeRtd.get_html_theme_path()] + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'dorisdoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'doris.tex', u'doris Documentation', + u'Apache Doris(Incubating)', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'Doris', u'Doris Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'Doris', u'Doris Documentation', + author, 'Apache Doris(Incubating)', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + + +# -- Extension configuration ------------------------------------------------- diff --git a/docs/website/source/index.rst b/docs/website/source/index.rst new file mode 100644 index 0000000000..5757173f66 --- /dev/null +++ b/docs/website/source/index.rst @@ -0,0 +1,11 @@ +Welcome to Doris's documentation! +================================= + + +.. toctree:: + :hidden: + + Docs/cn/administrator-guide/index + Docs/cn/extending-doris/index + Docs/cn/internal/index + Docs/cn/sql-reference/index