write once, use everywhere
Documentations will be written once, and will be converted to other format according to different application scenarios.
+---------------+ | 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.
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 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.
# Title
, and should have only one level 1 title.Description
, Syntax
, Examples
section in documents.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