From df30a48412df8a3df846867a44c1746b31c7eaf3 Mon Sep 17 00:00:00 2001 From: Ivan Blinkov Date: Tue, 16 May 2017 18:47:18 +0300 Subject: [PATCH] CLICKHOUSE-2981: basic styling of sphinx docs --- docs/Makefile | 13 +++-- docs/_static/custom.css | 88 +++++++++++++++++++++++++++++++++ docs/_static/logo.svg | 1 + docs/_templates/navigation.html | 10 ++++ docs/en/conf.py | 50 +++++++++++++------ docs/ru/conf.py | 50 +++++++++++++------ 6 files changed, 177 insertions(+), 35 deletions(-) create mode 100644 docs/_static/custom.css create mode 120000 docs/_static/logo.svg create mode 100644 docs/_templates/navigation.html diff --git a/docs/Makefile b/docs/Makefile index 8d8aca5abd2..64292d0b185 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = +SPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) SPHINXBUILD = sphinx-build PAPER = BUILDDIR = build @@ -15,11 +15,17 @@ endif # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) ru +ALLSPHINXOPTS = $(SPHINXOPTS) en # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) ru -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext +.PHONY: default help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +default: + $(SPHINXBUILD) -b html $(SPHINXOPTS) ru $(BUILDDIR)/docs/ru + $(SPHINXBUILD) -b html $(SPHINXOPTS) en $(BUILDDIR)/docs/en + SPHINX_TEMPLATES=../_templates $(SPHINXBUILD) -b singlehtml $(SPHINXOPTS) ru $(BUILDDIR)/docs/ru/single + SPHINX_TEMPLATES=../_templates $(SPHINXBUILD) -b singlehtml $(SPHINXOPTS) en $(BUILDDIR)/docs/en/single help: @echo "Please use \`make ' where is one of" @@ -175,3 +181,4 @@ pseudoxml: $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml @echo @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 00000000000..59b1ed2463c --- /dev/null +++ b/docs/_static/custom.css @@ -0,0 +1,88 @@ +div.sphinxsidebarwrapper { + padding: 2px 10px; +} + +div.sphinxsidebarwrapper p.logo { + float: left; + text-align: left; + margin: -4px 4px 0 0px; +} + +div.sphinxsidebar a { + border-bottom: none; + color: #000; +} + +pre { + padding: 4px; +} + +input { + display: block; + margin-bottom: 4px; +} + +@font-face { + font-family: 'Yandex Sans Text Web'; + src: url(https://yastatic.net/adv-www/_/yy5JveR58JFkc97waf-xp0i6_jM.eot); + src: url(https://yastatic.net/adv-www/_/yy5JveR58JFkc97waf-xp0i6_jM.eot?#iefix) format('embedded-opentype'), + url(https://yastatic.net/adv-www/_/CYblzLEXzCqQIvrYs7QKQe2omRk.woff2) format('woff2'), + url(https://yastatic.net/adv-www/_/pUcnOdRwl83MvPPzrNomhyletnA.woff) format('woff'), + url(https://yastatic.net/adv-www/_/vNFEmXOcGYKJ4AAidUprHWoXrLU.ttf) format('truetype'), + url(https://yastatic.net/adv-www/_/0w7OcWZM_QLP8x-LQUXFOgXO6dE.svg#YandexSansTextWeb-Bold) format('svg'); + font-weight: 700; + font-style: normal; + font-stretch: normal +} + +@font-face { + font-family: 'Yandex Sans Text Web'; + src: url(https://yastatic.net/adv-www/_/LI6l3L2RqcgxBe2pXmuUha37czQ.eot); + src: url(https://yastatic.net/adv-www/_/LI6l3L2RqcgxBe2pXmuUha37czQ.eot?#iefix) format('embedded-opentype'), + url(https://yastatic.net/adv-www/_/z3MYElcut0R2MF_Iw1RDNrstgYs.woff2) format('woff2'), + url(https://yastatic.net/adv-www/_/1jvKJ_-hCXl3s7gmFl-y_-UHTaI.woff) format('woff'), + url(https://yastatic.net/adv-www/_/9nzjfpCR2QHvK1EzHpDEIoVFGuY.ttf) format('truetype'), + url(https://yastatic.net/adv-www/_/gwyBTpxSwkFCF1looxqs6JokKls.svg#YandexSansTextWeb-Regular) format('svg'); + font-weight: 400; + font-style: normal; + font-stretch: normal +} + +@font-face { + font-family: 'Yandex Sans Text Web'; + src: url(https://yastatic.net/adv-www/_/ayAFYoY8swgBLhq_I56tKj2JftU.eot); + src: url(https://yastatic.net/adv-www/_/ayAFYoY8swgBLhq_I56tKj2JftU.eot?#iefix) format('embedded-opentype'), + url(https://yastatic.net/adv-www/_/lGQcYklLVV0hyvz1HFmFsUTj8_0.woff2) format('woff2'), + url(https://yastatic.net/adv-www/_/f0AAJ9GJ4iiwEmhG-7PWMHk6vUY.woff) format('woff'), + url(https://yastatic.net/adv-www/_/4UDe4nlVvgEJ-VmLWNVq3SxCsA.ttf) format('truetype'), + url(https://yastatic.net/adv-www/_/EKLr1STNokPqxLAQa_RyN82pL98.svg#YandexSansTextWeb-Light) format('svg'); + font-weight: 300; + font-style: normal; + font-stretch: normal +} + +@font-face { + font-family: 'Yandex Sans Display Web'; + src: url(https://yastatic.net/adv-www/_/H63jN0veW07XQUIA2317lr9UIm8.eot); + src: url(https://yastatic.net/adv-www/_/H63jN0veW07XQUIA2317lr9UIm8.eot?#iefix) format('embedded-opentype'), + url(https://yastatic.net/adv-www/_/sUYVCPUAQE7ExrvMS7FoISoO83s.woff2) format('woff2'), + url(https://yastatic.net/adv-www/_/v2Sve_obH3rKm6rKrtSQpf-eB7U.woff) format('woff'), + url(https://yastatic.net/adv-www/_/PzD8hWLMunow5i3RfJ6WQJAL7aI.ttf) format('truetype'), + url(https://yastatic.net/adv-www/_/lF_KG5g4tpQNlYIgA0e77fBSZ5s.svg#YandexSansDisplayWeb-Regular) format('svg'); + font-weight: 400; + font-style: normal; + font-stretch: normal +} + +@font-face { + font-family: 'Yandex Sans Display Web'; + src: url(https://yastatic.net/adv-www/_/g8_MyyKVquSZ3xEL6tarK__V9Vw.eot); + src: url(https://yastatic.net/adv-www/_/g8_MyyKVquSZ3xEL6tarK__V9Vw.eot?#iefix) format('embedded-opentype'), + url(https://yastatic.net/adv-www/_/LGiRvlfqQHlWR9YKLhsw5e7KGNA.woff2) format('woff2'), + url(https://yastatic.net/adv-www/_/40vXwNl4eYYMgteIVgLP49dwmfc.woff) format('woff'), + url(https://yastatic.net/adv-www/_/X6zG5x_wO8-AtwJ-vDLJcKC5228.ttf) format('truetype'), + url(https://yastatic.net/adv-www/_/ZKhaR0m08c8CRRL77GtFKoHcLYA.svg#YandexSansDisplayWeb-Light) format('svg'); + font-weight: 300; + font-style: normal; + font-stretch: normal +} diff --git a/docs/_static/logo.svg b/docs/_static/logo.svg new file mode 120000 index 00000000000..dbc7f998456 --- /dev/null +++ b/docs/_static/logo.svg @@ -0,0 +1 @@ +/Users/blinkov/ClickHouse/website/logo.svg \ No newline at end of file diff --git a/docs/_templates/navigation.html b/docs/_templates/navigation.html new file mode 100644 index 00000000000..f98fc4161f7 --- /dev/null +++ b/docs/_templates/navigation.html @@ -0,0 +1,10 @@ +

{{ _('Navigation') }}

+{{ toctree(includehidden=theme_sidebar_includehidden, collapse=False) }} +{% if theme_extra_nav_links %} +
+
    + {% for text, uri in theme_extra_nav_links.items() %} +
  • {{ text }}
    • + {% endfor %} +
+{% endif %} diff --git a/docs/en/conf.py b/docs/en/conf.py index 2f49322f3e5..efd3a4b2627 100644 --- a/docs/en/conf.py +++ b/docs/en/conf.py @@ -29,11 +29,11 @@ import os # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.mathjax', + 'alabaster' ] # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = [os.getenv('SPHINX_TEMPLATES', '')] # The suffix of source filenames. source_suffix = '.rst' @@ -46,20 +46,20 @@ master_doc = 'index' # General information about the project. project = u'ClickHouse' -copyright = u'2017, Alexey Milovidov' +copyright = u'2016–2017 Yandex LLC' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '1' +version = '' # The full version, including alpha/beta/rc tags. -release = '1' +release = '' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -#language = None +language = 'en' # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: @@ -100,12 +100,23 @@ pygments_style = 'sphinx' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +html_theme = 'alabaster' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} +font_family = '\'Yandex Sans Display Web\', Arial, sans-serif' +html_theme_options = { + 'logo': 'logo.svg', + 'logo_name': True, + 'github_user': 'yandex', + 'github_repo': 'ClickHouse', + 'github_button': False, + 'font_family': font_family, + 'head_font_family': font_family, + 'caption_font_family': font_family, + 'show_powered_by': False +} # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] @@ -129,7 +140,7 @@ html_theme = 'default' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = ['../_static'] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied @@ -145,7 +156,14 @@ html_static_path = ['_static'] #html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'relations.html', + 'searchbox.html', + ] +} # Additional templates that should be rendered to pages, maps page names to # template names. @@ -161,10 +179,10 @@ html_static_path = ['_static'] #html_split_index = False # If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True +html_show_sourcelink = False # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True +html_show_sphinx = False # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. #html_show_copyright = True @@ -178,7 +196,7 @@ html_static_path = ['_static'] #html_file_suffix = None # Output file base name for HTML help builder. -htmlhelp_basename = 'ClickHousedoc' +htmlhelp_basename = 'ClickHouse' # -- Options for LaTeX output --------------------------------------------- @@ -199,7 +217,7 @@ latex_elements = { # author, documentclass [howto, manual, or own class]). latex_documents = [ ('index', 'ClickHouse.tex', u'ClickHouse Documentation', - u'Alexey Milovidov', 'manual'), + u'Yandex LLC', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -229,7 +247,7 @@ latex_documents = [ # (source start file, name, description, authors, manual section). man_pages = [ ('index', 'clickhouse', u'ClickHouse Documentation', - [u'Alexey Milovidov'], 1) + [u'Yandex LLC'], 1) ] # If true, show URL addresses after external links. @@ -243,7 +261,7 @@ man_pages = [ # dir menu entry, description, category) texinfo_documents = [ ('index', 'ClickHouse', u'ClickHouse Documentation', - u'Alexey Milovidov', 'ClickHouse', 'One line description of project.', + u'Yandex LLC', 'ClickHouse', 'One line description of project.', 'Miscellaneous'), ] diff --git a/docs/ru/conf.py b/docs/ru/conf.py index 2f49322f3e5..978135de013 100644 --- a/docs/ru/conf.py +++ b/docs/ru/conf.py @@ -29,11 +29,11 @@ import os # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.mathjax', + 'alabaster' ] # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = [os.getenv('SPHINX_TEMPLATES', '')] # The suffix of source filenames. source_suffix = '.rst' @@ -46,20 +46,20 @@ master_doc = 'index' # General information about the project. project = u'ClickHouse' -copyright = u'2017, Alexey Milovidov' +copyright = u'2016–2017 Yandex LLC' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '1' +version = '' # The full version, including alpha/beta/rc tags. -release = '1' +release = '' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -#language = None +language = 'ru' # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: @@ -100,12 +100,23 @@ pygments_style = 'sphinx' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +html_theme = 'alabaster' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} +font_family = '\'Yandex Sans Display Web\', Arial, sans-serif' +html_theme_options = { + 'logo': 'logo.svg', + 'logo_name': True, + 'github_user': 'yandex', + 'github_repo': 'ClickHouse', + 'github_button': False, + 'font_family': font_family, + 'head_font_family': font_family, + 'caption_font_family': font_family, + 'show_powered_by': False +} # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] @@ -129,7 +140,7 @@ html_theme = 'default' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = ['../_static'] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied @@ -145,7 +156,14 @@ html_static_path = ['_static'] #html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'relations.html', + 'searchbox.html', + ] +} # Additional templates that should be rendered to pages, maps page names to # template names. @@ -161,10 +179,10 @@ html_static_path = ['_static'] #html_split_index = False # If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True +html_show_sourcelink = False # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True +html_show_sphinx = False # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. #html_show_copyright = True @@ -178,7 +196,7 @@ html_static_path = ['_static'] #html_file_suffix = None # Output file base name for HTML help builder. -htmlhelp_basename = 'ClickHousedoc' +htmlhelp_basename = 'ClickHouse' # -- Options for LaTeX output --------------------------------------------- @@ -199,7 +217,7 @@ latex_elements = { # author, documentclass [howto, manual, or own class]). latex_documents = [ ('index', 'ClickHouse.tex', u'ClickHouse Documentation', - u'Alexey Milovidov', 'manual'), + u'Yandex LLC', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -229,7 +247,7 @@ latex_documents = [ # (source start file, name, description, authors, manual section). man_pages = [ ('index', 'clickhouse', u'ClickHouse Documentation', - [u'Alexey Milovidov'], 1) + [u'Yandex LLC'], 1) ] # If true, show URL addresses after external links. @@ -243,7 +261,7 @@ man_pages = [ # dir menu entry, description, category) texinfo_documents = [ ('index', 'ClickHouse', u'ClickHouse Documentation', - u'Alexey Milovidov', 'ClickHouse', 'One line description of project.', + u'Yandex LLC', 'ClickHouse', 'One line description of project.', 'Miscellaneous'), ]