c7e526e050
* Additional .gitignore entries * Merge a bunch of small articles about system tables into single one * Merge a bunch of small articles about formats into single one * Adapt table with formats to English docs too * Add SPb meetup link to main page * Move Utilities out of top level of docs (the location is probably not yet final) + translate couple articles * Merge MacOS.md into build_osx.md * Move Data types higher in ToC * Publish changelog on website alongside documentation * Few fixes for en/table_engines/file.md * Use smaller header sizes in changelogs * Group up table engines inside ToC * Move table engines out of top level too * Specificy in ToC that query language is SQL based. Thats a bit excessive, but catches eye. * Move stuff that is part of query language into respective folder * Move table functions lower in ToC * Lost redirects.txt update * Do not rely on comments in yaml + fix few ru titles * Extract major parts of queries.md into separate articles * queries.md has been supposed to be removed * Fix weird translation * Fix a bunch of links * There is only table of contents left * "Query language" is actually part of SQL abbreviation * Change filename in README.md too * fix mistype * s/formats\/interfaces/interfaces\/formats/g * Remove extra clarification from header as it was too verbose, probably making it a bit more confusing * Empty article was supposed to be hidden * At least change incorrect title * Move special links to the bottom of nav and slightly highlight them * Skip hidden pages in bottom navigation too * Make front page of documentation to be part of Introduction * Make tables in introduction somewhat readable + move abbreviation definitions earlier * Some introduction text refactoring * Some docs introduction refactoring * Use admonitions instead of divs * Additional .gitignore * Treat .gif as images too * Clarify ToC item |
||
|---|---|---|
| .. | ||
| mkdocs-material-theme | ||
| build.py | ||
| concatenate.py | ||
| easy_edit.sh | ||
| README.md | ||
| requirements.txt | ||
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 (two languages in either single and multi page mode) as static HTMLs. The results are then put in correct directory structure.
Finally the infrustructure that builds ClickHouse official website just puts that directory structure into the same Docker container together with rest of website and deploys it to Yandex private cloud.
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 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.