ClickHouse/docs/tools
Ivan Blinkov ff1248cd28
[docs] extra F.A.Q. content (#11898)
* more content for F.A.Q.

* more content

* normalize

* more content

* maybe fix the docs check

* absolute img urls

* fix tests
2020-06-24 15:59:19 +03:00
..
translate [docs] extra F.A.Q. content (#11898) 2020-06-24 15:59:19 +03:00
amp.py support iframes in AMP version 2020-06-22 17:55:53 +03:00
blog.py Basic blog similar to docs (#11609) 2020-06-16 09:31:00 +03:00
build.py Basic blog similar to docs (#11609) 2020-06-16 09:31:00 +03:00
deploy-to-test.sh Try to purge website cache less aggressively (#9668) 2020-03-15 13:53:00 +03:00
easy_diff.py Major website front page refactoring (#9300) 2020-03-13 22:35:03 +03:00
easy_edit.sh Build Japanese docs (#7938) 2019-12-02 12:21:34 +03:00
github.py [docs] generate AMP versions for docs articles (#10732) 2020-05-08 11:04:09 +03:00
make_links.sh SQL reference refactoring (#10857) 2020-05-15 07:34:54 +03:00
mdx_clickhouse.py [docs] extra F.A.Q. content (#11898) 2020-06-24 15:59:19 +03:00
nav.py [docs] reorganized F.A.Q. 2020-06-22 16:35:41 +03:00
output.md [experimental] add "es" docs language as machine translated draft (#9787) 2020-03-21 07:11:51 +03:00
README.md Update README.md 2020-06-23 17:33:31 +03:00
redirects.py Basic blog similar to docs (#11609) 2020-06-16 09:31:00 +03:00
release.sh Tune cache purge 2020-05-19 17:32:24 +03:00
requirements.txt Bump requests from 2.23.0 to 2.24.0 in /docs/tools 2020-06-18 07:22:01 +00:00
single_page.py [docs] generate AMP versions for docs articles (#10732) 2020-05-08 11:04:09 +03:00
test.py Avoid logging error as a warning 2020-06-11 16:01:35 +03:00
util.py Get rid of toc_en.yml (#10023) 2020-04-03 16:23:32 +03:00
website.py [docs] extra F.A.Q. content (#11898) 2020-06-24 15:59:19 +03:00

How ClickHouse documentation is generated?

ClickHouse documentation is built using build.py script that uses mkdocs 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.

release.sh also pulls static files needed for official ClickHouse website from ../../website folder then pushes to specified GitHub repo to be served via GitHub Pages.

How to check if the documentation will look fine?

There are few options that are all useful depending on how large or complex your edits are.

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

Usually those also have some way to preview how Markdown will look like, which allows to catch basic errors like unclosed tags very early.

Use build.py

Itll take some effort to go through, but the result will be very close to production documentation.

For the first time youll need to:

1. Install wkhtmltopdf

Follow the instructions on it's official website: https://wkhtmltopdf.org/downloads.html

2. Install CLI tools from npm

  1. apt-get install npm for Debian/Ubuntu or brew install npm on Mac OS X.
  2. npm install -g purifycss amphtml-validator.

3. Set up virtualenv

$ cd ClickHouse/docs/tools
$ mkdir venv
$ virtualenv -p $(which python3) venv
$ source venv/bin/activate
$ pip3 install -r requirements.txt

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.

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.

How to subscribe on documentation changes?

At the moment theres no easy way to do just that, but you can consider:

  • 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.
  • Some search engines allow to subscribe on specific website changes via email and you can opt-in for that for https://clickhouse.tech.