docs: use alabaster theme

It's not all perfect (yet) but way cleaner and simpler to use than
the sphinx one.

Custom do the scrolling for the fixed side bar and make some other
slight adjustments.

Main issue for now is that the "Developer Appendix" is always shown
in the navigation tree, but we only include that toctree for
devbuilds...

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>

diff --git a/docs/Makefile b/docs/Makefile
index 8d1e8a1b4eaa13bb3978a38752bdd139f43ab236..4e2f9606baf7ca49f29cd80d5d0049303be1bfe3 100644 (file)
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -76,6 +76,8 @@ onlinehelpinfo:
 .PHONY: html
 html: ${GENERATED_SYNOPSIS}
        $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+       cp images/proxmox-logo.svg $(BUILDDIR)/html/_static/
+       cp custom.css $(BUILDDIR)/html/_static/
        @echo
        @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 

diff --git a/docs/conf.py b/docs/conf.py
index a9d45c2e0df3a8e3b161c26225ccbefcb1ea242c..b1cadd081927a10e531d13f3e15000352f09a523 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -156,13 +156,32 @@ todo_include_todos = True
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinxdoc'
+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 = {}
+html_theme_options = {
+    'fixed_sidebar': True,
+    #'sidebar_includehidden': False,
+    'sidebar_collapse': False, # FIXME: documented, but does not works?!
+    'show_relbar_bottom': True, # FIXME: documented, but does not works?!
+    'show_powered_by': False,
+
+    'logo': 'proxmox-logo.svg',
+    'logo_name': True, # show project name below logo
+    #'logo_text_align': 'center',
+    #'description': 'Fast, Secure & Efficient.',
+
+    'sidebar_width': '300px',
+    'page_width': '1280px',
+    # font styles
+    'head_font_family': 'Lato, sans-serif',
+    'caption_font_family': 'Lato, sans-serif',
+    'caption_font_size': '20px',
+    'font_family': 'Open Sans, sans-serif',
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
@@ -179,7 +198,7 @@ html_theme = 'sphinxdoc'
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 #
-html_logo = 'images/proxmox-logo.svg'
+#html_logo = 'images/proxmox-logo.svg' # replaced by html_theme_options.logo
 
 # The name of an image file (relative to this directory) to use as a favicon of
 # the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -232,7 +251,7 @@ html_static_path = ['_static']
 
 # 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.
 #

diff --git a/docs/custom.css b/docs/custom.css
new file mode 100644 (file)
index 0000000..b9a575e
--- /dev/null
+++ b/docs/custom.css
@@ -0,0 +1,11 @@
+div.sphinxsidebar {
+    height: calc(100% - 20px);
+    overflow: auto;
+}
+
+h1.logo-name {
+    font-size: 24px;
+}
+pre {
+    padding: 5px 10px;
+}