c1969a3fb3
Doris support choose medium when create table, and the cluster balance strategy is dependent between different storage medium, and most use will not specify the storage medium when create table, even they kown that they should choose a storage medium, they have no idea about the cluster's storage medium, so, I think we should make storage_medium and storage_cooldown_time configurable, and this should be the admin's responsibility. For Example, if the cluster's storage medium is HDD, but we need to change part of machines to SSD, if we change the machine, the tablets before change is stored in HDD and they can't find a dest path to migrate, and user will create table as usual, it will make all tablets stored in old machines and the new machines will only store a little tablets. Without this config the only way is admin need to traverse all partitions in cluster and change the property of storage_medium, it will increase operational and maintenance costs. So I add a FE config default_storage_medium, so that user can set the default storage medium.
Philosophy
write once, use everywhere
Documentations will be written once, and will be converted to other format according to different application scenarios.
Implementation
+---------------+
| Documentation |
+-------+-------+
|
+-------+-------+
| Doc Builder |
+-------+-------+
|
+--------------------------------+
| | |
+---+---+ +---+----+ +-----+----+
| PDF | | HTML | .... | Help Doc |
+-------+ +--------+ +----------+
Documentation：Text contents which is written by human. And this is the only place for documentation. Doc Builder: Tools that convert documentations to other format, such as PDF, HTML. There could be many tools, and we can use different tools to convert documentation to different formats.
Organization
docs/documentation: Root directory for documentation. And for different languages, there is a root directory for it. For example,docs/documentation/cnis the Chinese documentation's root directory.docs/scripts: Place ofDoc Builder.docs/resources: Resources that are referenced in documentation, such as pictures.docs/website: A website for documentations built with Sphinx using a theme provided by Read-the-Docs.
Constraints
- All documents are written in Markdown format, and file name is end with ".md".
- All documents are started with level 1 title
# Title, and should have only one level 1 title. - Names of file and directory are in lowercase letters, and use dashes as separator.
- Documentation can be constructed as a directory or a single Markdown file, these two formats equal with each other in logical. Relationship is represented by parent-child directory in directory format, and by title level in file format. It is recommended to use directory format to manage a large documentation, because it is easy to maintain.
- A directory corresponds to a title, and readme.md in this directory is its content. Other documents in this directory is its sub-sections.
- For manual like section, such as function description, there should be
Description,Syntax,Examplessection in documents.
Level Directories
- doris-concepts
- installing
- getting-started
- administrator-guide
- sql-references
- best-practices
- internals
- community
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
Docs Styles
There are some styles need to be followed.
SQL-Statement
Docs under documentation/cn/sql-reference/sql-statements/ must obey the following style
# TITLE(capital)
## description
The description of this doc. The "## description" must be reserved, with a following empty line.
## keyword
The keyword of this doc. Usually, this can be the title of this doc.
The "## keyword" must be reserved, with a following empty line.