ClickHouse/docs/tools
Ivan Blinkov 387cbca505
Introduction refactoring + a bunch of docs fixes (#8010)
* Create SECURITY.md

* [experimental] auto-mark documentation PRs with labels

* revert #6544

* Sync RPM packages instructions to other docs languages

* Move tutorial to documentation with old content (for now)

* refactor installation guide a bit

* add ../en/getting_started/index.md

* Rename ya_metrica_task.md

* Rename ya_metrica_task.md

* Refactor Yandex.Metrica dataset description

* WIP on rewriting tutorial

* tmp commit

* lots of docs fixes

* partially revert c136bee4ce

* try to fix docs build in CI

* try to fix docs build in CI

* few minor improvements

* Quick refactoring of last portion of tutorial (not thoroughly tested though)

* fix link
2019-12-05 19:36:51 +03:00
..
mkdocs-material-theme Introduction refactoring + a bunch of docs fixes (#8010) 2019-12-05 19:36:51 +03:00
build.py Build Japanese docs (#7938) 2019-12-02 12:21:34 +03:00
concatenate.py Added comprehension to improve performance 2019-11-20 09:12:42 +03:00
easy_diff.py add show help & no-pager 2019-10-29 14:20:12 +08:00
easy_edit.sh Build Japanese docs (#7938) 2019-12-02 12:21:34 +03:00
github.py Changed repository URL 2019-09-23 19:18:19 +03:00
make_links.sh Introduction refactoring + a bunch of docs fixes (#8010) 2019-12-05 19:36:51 +03:00
mdx_clickhouse.py add lost else 2018-12-25 11:43:07 +03:00
README.md Improve #5021 (#5023) 2019-04-17 12:02:37 +03:00
release.sh Remove -f option from curl 2019-04-17 16:32:15 +03:00
requirements.txt add easy diff for document tracking 2019-10-28 11:20:39 +08:00
test.py Docs fixes 2019-06-07 14:06:23 +03:00
util.py Support building docs for stable releases in addition to docs from master (#4940) 2019-04-08 19:01:54 +03:00
website.py fix building of docs with python3 (#5021) 2019-04-17 11:15:42 +03:00

How ClickHouse documentation is generated?

ClickHouse documentation is built using build.py script that uses mkdocs library and it's dependencies to separately build all version of documentations (all languages in either single and multi page mode) as static HTMLs. The results are then put in correct directory structure. It can also generate PDF version.

release.sh also pulls static files needed for official ClickHouse website from ../../website folder, packs them alongside docs into Docker container and tries to deploy it (possible only from Yandex private network).

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.

Install Markdown editor or plugin for your IDE

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

Use build.py

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

For the first time you'll need to install wkhtmltopdf and set up virtualenv:

$ cd ClickHouse/docs/tools
$ mkdir venv
$ virtualenv venv
$ source venv/bin/activate
$ pip install -r requirements.txt

Then running build.py without args (there are some, check build.py --help) will generate ClickHouse/docs/build folder with complete static html website.

You can just directly open those HTML files in browser, but usually it is more convenient to have some sort of HTTP server hosting them. For example, you can launch one by running cd ClickHouse/docs/build && python -m SimpleHTTPServer 8888 and then go to http://localhost:8888 in browser.

Commit blindly

Then push to GitHub so you can use it's preview. It's better to use previous methods too though.

How to subscribe on documentation changes?

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

  • Hit the "Watch" button on top of GitHub web interface to know as early as possible, even during pull request.
  • Some search engines allow to subscribe on specific website changes via email and you can opt-in for that for https://clickhouse.yandex.