ClickHouse/docs/tools/README.md

56 lines
3.1 KiB
Markdown
Raw Normal View History

## How ClickHouse documentation is generated? {#how-clickhouse-documentation-is-generated}
2018-07-11 13:45:13 +00:00
2020-03-22 12:08:47 +00:00
ClickHouse documentation is built using [build.py](build.py) script that uses [mkdocs](https://www.mkdocs.org) library and its dependencies to separately build all version of documentations (all languages in either single and multi page mode) as static HTMLs and then a PDF for each single page version. The results are then put in the correct directory structure. It is recommended to use Python 3.7 to run this script.
2018-07-11 13:45:13 +00:00
2020-03-22 12:08:47 +00:00
[release.sh](release.sh) also pulls static files needed for [official ClickHouse website](https://clickhouse.tech) from [../../website](../../website) folder then pushes to specified GitHub repo to be served via [GitHub Pages](https://pages.github.com).
2018-07-11 13:45:13 +00:00
## How to check if the documentation will look fine? {#how-to-check-if-the-documentation-will-look-fine}
2018-07-11 13:45:13 +00:00
There are few options that are all useful depending on how large or complex your edits are.
2020-03-22 12:08:47 +00:00
### Use GitHub web interface to edit
GitHub has Markdown support with preview feature, but the details of GitHub Markdown dialect are a bit different in ClickHouse documentation.
### Install Markdown editor or plugin for your IDE {#install-markdown-editor-or-plugin-for-your-ide}
2018-07-11 13:45:13 +00:00
2020-03-22 12:08:47 +00:00
Usually those also have some way to preview how Markdown will look like, which allows to catch basic errors like unclosed tags very early.
2018-07-11 13:45:13 +00:00
### Use build.py {#use-build-py}
2018-07-11 13:45:13 +00:00
Itll take some effort to go through, but the result will be very close to production documentation.
2018-07-11 13:45:13 +00:00
2020-06-23 14:32:54 +00:00
For the first time youll need to:
#### 1. Install [wkhtmltopdf](https://wkhtmltopdf.org/)
Follow the instructions on it's official website: <https://wkhtmltopdf.org/downloads.html>
#### 2. Install CLI tools from npm
2020-12-21 20:04:22 +00:00
1. `sudo apt-get install npm` for Debian/Ubuntu or `brew install npm` on Mac OS X.
2. `sudo npm install -g purify-css amphtml-validator`.
2020-06-23 14:32:54 +00:00
2020-06-23 14:33:31 +00:00
#### 3. Set up virtualenv
2018-07-11 13:45:13 +00:00
``` bash
$ cd ClickHouse/docs/tools
$ mkdir venv
2020-03-22 12:08:47 +00:00
$ virtualenv -p $(which python3) venv
2018-07-11 13:45:13 +00:00
$ source venv/bin/activate
2020-03-22 12:08:47 +00:00
$ pip3 install -r requirements.txt
2018-07-11 13:45:13 +00:00
```
2020-06-23 14:32:54 +00:00
#### 4. Run build.py
When all prerequisites are installed, running `build.py` without args (there are some, check `build.py --help`) will generate `ClickHouse/docs/build` folder with complete static html website.
2018-07-11 13:45:13 +00:00
2020-03-22 12:12:15 +00:00
The easiest way to see the result is to use `--livereload=8888` argument of build.py. Alternatively, you can manually launch a HTTP server to serve the docs, for example by running `cd ClickHouse/docs/build && python3 -m http.server 8888`. Then go to http://localhost:8888 in browser. Feel free to use any other port instead of 8888.
2018-07-11 13:45:13 +00:00
## How to subscribe on documentation changes? {#how-to-subscribe-on-documentation-changes}
2018-07-11 13:45:13 +00:00
At the moment theres no easy way to do just that, but you can consider:
2018-07-11 13:45:13 +00:00
2021-03-22 15:29:19 +00:00
- To hit the “Watch” button on top of GitHub web interface to know as early as possible, even during pull request. Alternative to this is `#github-activity` channel of [public ClickHouse Slack](https://join.slack.com/t/clickhousedb/shared_invite/zt-nwwakmk4-xOJ6cdy0sJC3It8j348~IA).
- Some search engines allow to subscribe on specific website changes via email and you can opt-in for that for https://clickhouse.tech.