From 53ed6d7d1e678d7486337ce67a2f17b30bac21ac Mon Sep 17 00:00:00 2001 From: nodiscc Date: Thu, 26 Jan 2017 18:52:54 +0100 Subject: Generate HTML documentation using MkDocs (WIP) MkDocs is a static site generator geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML file. * http://www.mkdocs.org/ * http://www.mkdocs.org/user-guide/configuration/ Ref. #312 * remove pandoc-generated HTML documentation * move markdown doc to doc/md/, * mkdocs.yml: * generate HTML doc in doc/html * add pages TOC/ordering * use index.md as index page * Makefile: remove execute permissions from generated files * Makefile: rewrite htmlpages GFM to markdown conversion using sed: awk expression aslo matched '][' which causes invalid output on complex links with images or code blocks * Add mkdocs.yml to .gitattributes, exclude this file from release archives * Makefile: rename: htmldoc -> doc_html target * run make doc: pull latest markdown documentation from wiki * run make htmlpages: update html documentation --- doc/html/css/theme_extra.css | 193 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 doc/html/css/theme_extra.css (limited to 'doc/html/css/theme_extra.css') diff --git a/doc/html/css/theme_extra.css b/doc/html/css/theme_extra.css new file mode 100644 index 00000000..e53d320a --- /dev/null +++ b/doc/html/css/theme_extra.css @@ -0,0 +1,193 @@ +/* + * Sphinx doesn't have support for section dividers like we do in + * MkDocs, this styles the section titles in the nav + * + * https://github.com/mkdocs/mkdocs/issues/175 + */ +.wy-menu-vertical span { + line-height: 18px; + padding: 0.4045em 1.618em; + display: block; + position: relative; + font-size: 90%; + color: #838383; +} + +.wy-menu-vertical .subnav a { + padding: 0.4045em 2.427em; +} + +/* + * Long navigations run off the bottom of the screen as the nav + * area doesn't scroll. + * + * https://github.com/mkdocs/mkdocs/pull/202 + * + * Builds upon pull 202 https://github.com/mkdocs/mkdocs/pull/202 + * to make toc scrollbar end before navigations buttons to not be overlapping. + */ +.wy-nav-side { + height: calc(100% - 45px); + overflow-y: auto; + min-height: 0; +} + +.rst-versions{ + border-top: 0; + height: 45px; +} + +@media screen and (max-width: 768px) { + .wy-nav-side { + height: 100%; + } +} + +/* + * readthedocs theme hides nav items when the window height is + * too small to contain them. + * + * https://github.com/mkdocs/mkdocs/issues/#348 + */ +.wy-menu-vertical ul { + margin-bottom: 2em; +} + +/* + * Wrap inline code samples otherwise they shoot of the side and + * can't be read at all. + * + * https://github.com/mkdocs/mkdocs/issues/313 + * https://github.com/mkdocs/mkdocs/issues/233 + * https://github.com/mkdocs/mkdocs/issues/834 + */ +code { + white-space: pre-wrap; + word-wrap: break-word; + padding: 2px 5px; +} + +/** + * Make code blocks display as blocks and give them the appropriate + * font size and padding. + * + * https://github.com/mkdocs/mkdocs/issues/855 + * https://github.com/mkdocs/mkdocs/issues/834 + * https://github.com/mkdocs/mkdocs/issues/233 + */ +pre code { + white-space: pre; + word-wrap: normal; + display: block; + padding: 12px; + font-size: 12px; +} + +/* + * Fix link colors when the link text is inline code. + * + * https://github.com/mkdocs/mkdocs/issues/718 + */ +a code { + color: #2980B9; +} +a:hover code { + color: #3091d1; +} +a:visited code { + color: #9B59B6; +} + +/* + * The CSS classes from highlight.js seem to clash with the + * ReadTheDocs theme causing some code to be incorrectly made + * bold and italic. + * + * https://github.com/mkdocs/mkdocs/issues/411 + */ +pre .cs, pre .c { + font-weight: inherit; + font-style: inherit; +} + +/* + * Fix some issues with the theme and non-highlighted code + * samples. Without and highlighting styles attached the + * formatting is broken. + * + * https://github.com/mkdocs/mkdocs/issues/319 + */ +.no-highlight { + display: block; + padding: 0.5em; + color: #333; +} + + +/* + * Additions specific to the search functionality provided by MkDocs + */ + +.search-results article { + margin-top: 23px; + border-top: 1px solid #E1E4E5; + padding-top: 24px; +} + +.search-results article:first-child { + border-top: none; +} + +form .search-query { + width: 100%; + border-radius: 50px; + padding: 6px 12px; /* csslint allow: box-model */ + border-color: #D1D4D5; +} + +.wy-menu-vertical li ul { + display: inherit; +} + +.wy-menu-vertical li ul.subnav ul.subnav{ + padding-left: 1em; +} + +.wy-menu-vertical .subnav li.current > a { + padding-left: 2.42em; +} +.wy-menu-vertical .subnav li.current > ul li a { + padding-left: 3.23em; +} + +/* + * Improve inline code blocks within admonitions. + * + * https://github.com/mkdocs/mkdocs/issues/656 + */ + .admonition code { + color: #404040; + border: 1px solid #c7c9cb; + border: 1px solid rgba(0, 0, 0, 0.2); + background: #f8fbfd; + background: rgba(255, 255, 255, 0.7); +} + +/* + * Account for wide tables which go off the side. + * Override borders to avoid wierdness on narrow tables. + * + * https://github.com/mkdocs/mkdocs/issues/834 + * https://github.com/mkdocs/mkdocs/pull/1034 + */ +.rst-content .section .docutils { + width: 100%; + overflow: auto; + display: block; + border: none; +} + +td, th { + border: 1px solid #e1e4e5 !important; /* csslint allow: important */ + border-collapse: collapse; +} -- cgit v1.2.3