Rework Ceres documentation as new website This reworks the Ceres Sphinx documentation such that it can function as the main Ceres website, now hosted at ceres-solver.org. This also changes to the theme sphinx_rtd_theme used by Read The Docs; this theme has strong mobile support and is well enough designed. Change-Id: I63232d985859a6dac94ff58f08bf81eb2b9e7f99
diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html new file mode 100644 index 0000000..61c8eb5 --- /dev/null +++ b/docs/source/_templates/layout.html
@@ -0,0 +1,13 @@ +{% extends "!layout.html" %} + +{% block footer %} +{{ super() }} +<script> + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + ga('create', 'UA-49769510-1', 'ceres-solver.org'); + ga('send', 'pageview'); +</script> +{% endblock %}
diff --git a/docs/source/_themes/armstrong/LICENSE b/docs/source/_themes/armstrong/LICENSE deleted file mode 100644 index 894aa01..0000000 --- a/docs/source/_themes/armstrong/LICENSE +++ /dev/null
@@ -1,26 +0,0 @@ -Copyright (c) 2011 Bay Citizen & Texas Tribune - -Original ReadTheDocs.org code -Copyright (c) 2010 Charles Leifer, Eric Holscher, Bobby Grace - -Permission is hereby granted, free of charge, to any person -obtaining a copy of this software and associated documentation -files (the "Software"), to deal in the Software without -restriction, including without limitation the rights to use, -copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following -conditions: - -The above copyright notice and this permission notice shall be -included in all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, -EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES -OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND -NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT -HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, -WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -OTHER DEALINGS IN THE SOFTWARE. -
diff --git a/docs/source/_themes/armstrong/globaltoc.html b/docs/source/_themes/armstrong/globaltoc.html deleted file mode 100644 index 68d82fa..0000000 --- a/docs/source/_themes/armstrong/globaltoc.html +++ /dev/null
@@ -1,11 +0,0 @@ -{# - basic/globaltoc.html - ~~~~~~~~~~~~~~~~~~~~ - - Sphinx sidebar template: global table of contents. - - :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. - :license: BSD, see LICENSE for details. -#} -<h3><a href="{{ pathto(master_doc) }}">{{ _('Ceres Solver') }}</a></h3> -{{ toctree(includehidden=True) }}
diff --git a/docs/source/_themes/armstrong/layout.html b/docs/source/_themes/armstrong/layout.html deleted file mode 100644 index 3faa34c..0000000 --- a/docs/source/_themes/armstrong/layout.html +++ /dev/null
@@ -1,80 +0,0 @@ -{% extends "basic/layout.html" %} - -{% set script_files = script_files + [pathto("_static/searchtools.js", 1)] %} - -{% block htmltitle %} -{{ super() }} - -<meta name="viewport" content="width=device-width; initial-scale=1.0; maximum-scale=1.0; user-scalable=0;"/> - -{% endblock %} - - -{%- macro sidebar() %} - {%- if render_sidebar %} - <div class="sphinxsidebar"> - <div class="sphinxsidebarwrapper"> - {%- block sidebarlogo %} - {%- if logo %} - <p class="logo"><a href="{{ pathto(master_doc) }}"> - <img class="logo" src="{{ pathto('_static/' + logo, 1) }}" alt="Logo"/> - </a></p> - {%- endif %} - {%- endblock %} - {%- if sidebars != None %} - {#- new style sidebar: explicitly include/exclude templates #} - {%- for sidebartemplate in sidebars %} - {%- include sidebartemplate %} - {%- endfor %} - {%- else %} - {#- old style sidebars: using blocks -- should be deprecated #} - {%- block sidebartoc %} - {%- include "globaltoc.html" %} - {%- endblock %} - {%- block sidebarsourcelink %} - {%- include "sourcelink.html" %} - {%- endblock %} - {%- if customsidebar %} - {%- include customsidebar %} - {%- endif %} - {%- block sidebarsearch %} - {%- include "searchbox.html" %} - {%- endblock %} - {%- endif %} - </div> - </div> - {%- endif %} -{%- endmacro %} - - -{% block footer %} -<div class="footer"> -{%- if show_copyright %} - {%- if hasdoc('copyright') %} - {% trans path=pathto('copyright'), copyright=copyright|e %}© <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %} - {%- else %} - {% trans copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} - {%- endif %} -{%- endif %} -{%- if last_updated %} - {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} -{%- endif %} -</div> - - -{% if theme_analytics_code %} -<!-- Google Analytics Code --> -<script type="text/javascript"> - var _gaq = _gaq || []; - _gaq.push(['_setAccount', '{{ theme_analytics_code }}']); - _gaq.push(['_trackPageview']); - - (function() { - var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; - ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; - var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); - })(); -</script> -{% endif %} - -{% endblock %}
diff --git a/docs/source/_themes/armstrong/rtd-themes.conf b/docs/source/_themes/armstrong/rtd-themes.conf deleted file mode 100644 index 5930488..0000000 --- a/docs/source/_themes/armstrong/rtd-themes.conf +++ /dev/null
@@ -1,65 +0,0 @@ -[theme] -inherit = default -stylesheet = rtd.css -pygment_style = default -show_sphinx = False - -[options] -show_rtd = True - -white = #ffffff -almost_white = #f8f8f8 -barely_white = #f2f2f2 -dirty_white = #eeeeee -almost_dirty_white = #e6e6e6 -dirtier_white = #dddddd -lighter_gray = #cccccc -gray_a = #aaaaaa -gray_9 = #999999 -light_gray = #888888 -gray_7 = #777777 -gray = #666666 -dark_gray = #444444 -gray_2 = #222222 -black = #111111 -light_color = #e8ecef -light_medium_color = #DDEAF0 -medium_color = #8ca1af -medium_color_link = #86989b -medium_color_link_hover = #a6b8bb -dark_color = #465158 - -h1 = #000000 -h2 = #465158 -h3 = #6c818f - -link_color = #444444 -link_color_decoration = #CCCCCC - -medium_color_hover = #697983 -green_highlight = #8ecc4c - - -positive_dark = #609060 -positive_medium = #70a070 -positive_light = #e9ffe9 - -negative_dark = #900000 -negative_medium = #b04040 -negative_light = #ffe9e9 -negative_text = #c60f0f - -ruler = #abc - -viewcode_bg = #f4debf -viewcode_border = #ac9 - -highlight = #ffe080 - -code_background = #eeeeee - -background = #465158 -background_link = #ffffff -background_link_half = #ffffff -background_text = #eeeeee -background_text_link = #86989b
diff --git a/docs/source/_themes/armstrong/static/rtd.css_t b/docs/source/_themes/armstrong/static/rtd.css_t deleted file mode 100644 index 90354c3..0000000 --- a/docs/source/_themes/armstrong/static/rtd.css_t +++ /dev/null
@@ -1,781 +0,0 @@ -/* - * rtd.css - * ~~~~~~~~~~~~~~~ - * - * Sphinx stylesheet -- sphinxdoc theme. Originally created by - * Armin Ronacher for Werkzeug. - * - * Customized for ReadTheDocs by Eric Pierce & Eric Holscher - * - * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. - * :license: BSD, see LICENSE for details. - * - */ - -/* RTD colors - * light blue: {{ theme_light_color }} - * medium blue: {{ theme_medium_color }} - * dark blue: {{ theme_dark_color }} - * dark grey: {{ theme_grey_color }} - * - * medium blue hover: {{ theme_medium_color_hover }}; - * green highlight: {{ theme_green_highlight }} - * light blue (project bar): {{ theme_light_color }} - */ - -@import url("basic.css"); - -/* PAGE LAYOUT -------------------------------------------------------------- */ - -body { - font: 100%/1.5 "ff-meta-web-pro-1","ff-meta-web-pro-2",Arial,"Helvetica Neue",sans-serif; - text-align: center; - color: black; - background-color: {{ theme_background }}; - padding: 0; - margin: 0; -} - -div.document { - text-align: left; - background-color: {{ theme_light_color }}; -} - -div.bodywrapper { - background-color: {{ theme_white }}; - border-left: 1px solid {{ theme_lighter_gray }}; - border-bottom: 1px solid {{ theme_lighter_gray }}; - margin: 0 0 0 16em; -} - -div.body { - margin: 0; - padding: 0.5em 1.3em; - max-width: 55em; - min-width: 20em; -} - -div.related { - font-size: 1em; - background-color: {{ theme_background }}; -} - -div.documentwrapper { - float: left; - width: 100%; - background-color: {{ theme_light_color }}; -} - - -/* HEADINGS --------------------------------------------------------------- */ - -h1 { - margin: 0; - padding: 0.7em 0 0.3em 0; - font-size: 1.5em; - line-height: 1.15; - color: {{ theme_h1 }}; - clear: both; -} - -h2 { - margin: 2em 0 0.2em 0; - font-size: 1.35em; - padding: 0; - color: {{ theme_h2 }}; -} - -h3 { - margin: 1em 0 -0.3em 0; - font-size: 1.2em; - color: {{ theme_h3 }}; -} - -div.body h1 a, div.body h2 a, div.body h3 a, div.body h4 a, div.body h5 a, div.body h6 a { - color: black; -} - -h1 a.anchor, h2 a.anchor, h3 a.anchor, h4 a.anchor, h5 a.anchor, h6 a.anchor { - display: none; - margin: 0 0 0 0.3em; - padding: 0 0.2em 0 0.2em; - color: {{ theme_gray_a }} !important; -} - -h1:hover a.anchor, h2:hover a.anchor, h3:hover a.anchor, h4:hover a.anchor, -h5:hover a.anchor, h6:hover a.anchor { - display: inline; -} - -h1 a.anchor:hover, h2 a.anchor:hover, h3 a.anchor:hover, h4 a.anchor:hover, -h5 a.anchor:hover, h6 a.anchor:hover { - color: {{ theme_gray_7 }}; - background-color: {{ theme_dirty_white }}; -} - - -/* LINKS ------------------------------------------------------------------ */ - -/* Normal links get a pseudo-underline */ -a { - color: {{ theme_link_color }}; - text-decoration: none; - border-bottom: 1px solid {{ theme_link_color_decoration }}; -} - -/* Links in sidebar, TOC, index trees and tables have no underline */ -.sphinxsidebar a, -.toctree-wrapper a, -.indextable a, -#indices-and-tables a { - color: {{ theme_dark_gray }}; - text-decoration: none; - border-bottom: none; -} - -/* Most links get an underline-effect when hovered */ -a:hover, -div.toctree-wrapper a:hover, -.indextable a:hover, -#indices-and-tables a:hover { - color: {{ theme_black }}; - text-decoration: none; - border-bottom: 1px solid {{ theme_black }}; -} - -/* Footer links */ -div.footer a { - color: {{ theme_background_text_link }}; - text-decoration: none; - border: none; -} -div.footer a:hover { - color: {{ theme_medium_color_link_hover }}; - text-decoration: underline; - border: none; -} - -/* Permalink anchor (subtle grey with a red hover) */ -div.body a.headerlink { - color: {{ theme_lighter_gray }}; - font-size: 1em; - margin-left: 6px; - padding: 0 4px 0 4px; - text-decoration: none; - border: none; -} -div.body a.headerlink:hover { - color: {{ theme_negative_text }}; - border: none; -} - - -/* NAVIGATION BAR --------------------------------------------------------- */ - -div.related ul { - height: 2.5em; -} - -div.related ul li { - margin: 0; - padding: 0.65em 0; - float: left; - display: block; - color: {{ theme_background_link_half }}; /* For the >> separators */ - font-size: 0.8em; -} - -div.related ul li.right { - float: right; - margin-right: 5px; - color: transparent; /* Hide the | separators */ -} - -/* "Breadcrumb" links in nav bar */ -div.related ul li a { - order: none; - background-color: inherit; - font-weight: bold; - margin: 6px 0 6px 4px; - line-height: 1.75em; - color: {{ theme_background_link }}; - text-shadow: 0 1px rgba(0, 0, 0, 0.5); - padding: 0.4em 0.8em; - border: none; - border-radius: 3px; -} -/* previous / next / modules / index links look more like buttons */ -div.related ul li.right a { - margin: 0.375em 0; - background-color: {{ theme_medium_color_hover }}; - text-shadow: 0 1px rgba(0, 0, 0, 0.5); - border-radius: 3px; - -webkit-border-radius: 3px; - -moz-border-radius: 3px; -} -/* All navbar links light up as buttons when hovered */ -div.related ul li a:hover { - background-color: {{ theme_medium_color }}; - color: {{ theme_white }}; - text-decoration: none; - border-radius: 3px; - -webkit-border-radius: 3px; - -moz-border-radius: 3px; -} -/* Take extra precautions for tt within links */ -a tt, -div.related ul li a tt { - background: inherit !important; - color: inherit !important; -} - - -/* SIDEBAR ---------------------------------------------------------------- */ - -div.sphinxsidebarwrapper { - padding: 0; -} - -div.sphinxsidebar { - margin: 0; - margin-left: -100%; - float: left; - top: 3em; - left: 0; - padding: 0 1em; - width: 14em; - font-size: 1em; - text-align: left; - background-color: {{ theme_light_color }}; -} - -div.sphinxsidebar img { - max-width: 12em; -} - -div.sphinxsidebar h3, div.sphinxsidebar h4 { - margin: 1.2em 0 0.3em 0; - font-size: 1em; - padding: 0; - color: {{ theme_gray_2 }}; - font-family: "ff-meta-web-pro-1", "ff-meta-web-pro-2", "Arial", "Helvetica Neue", sans-serif; -} - -div.sphinxsidebar h3 a { - color: {{ theme_grey_color }}; -} - -div.sphinxsidebar ul, -div.sphinxsidebar p { - margin-top: 0; - padding-left: 0; - line-height: 130%; - background-color: {{ theme_light_color }}; -} - -/* No bullets for nested lists, but a little extra indentation */ -div.sphinxsidebar ul ul { - list-style-type: none; - margin-left: 1.5em; - padding: 0; -} - -/* A little top/bottom padding to prevent adjacent links' borders - * from overlapping each other */ -div.sphinxsidebar ul li { - padding: 1px 0; -} - -/* A little left-padding to make these align with the ULs */ -div.sphinxsidebar p.topless { - padding-left: 0 0 0 1em; -} - -/* Make these into hidden one-liners */ -div.sphinxsidebar ul li, -div.sphinxsidebar p.topless { - white-space: nowrap; - overflow: hidden; -} -/* ...which become visible when hovered */ -div.sphinxsidebar ul li:hover, -div.sphinxsidebar p.topless:hover { - overflow: visible; -} - -/* Search text box and "Go" button */ -#searchbox { - margin-top: 2em; - margin-bottom: 1em; - background: {{ theme_dirtier_white }}; - padding: 0.5em; - border-radius: 6px; - -moz-border-radius: 6px; - -webkit-border-radius: 6px; -} -#searchbox h3 { - margin-top: 0; -} - -/* Make search box and button abut and have a border */ -input, -div.sphinxsidebar input { - border: 1px solid {{ theme_gray_9 }}; - float: left; -} - -/* Search textbox */ -input[type="text"] { - margin: 0; - padding: 0 3px; - height: 20px; - width: 144px; - border-top-left-radius: 3px; - border-bottom-left-radius: 3px; - -moz-border-radius-topleft: 3px; - -moz-border-radius-bottomleft: 3px; - -webkit-border-top-left-radius: 3px; - -webkit-border-bottom-left-radius: 3px; -} -/* Search button */ -input[type="submit"] { - margin: 0 0 0 -1px; /* -1px prevents a double-border with textbox */ - height: 22px; - color: {{ theme_dark_gray }}; - background-color: {{ theme_light_color }}; - padding: 1px 4px; - font-weight: bold; - border-top-right-radius: 3px; - border-bottom-right-radius: 3px; - -moz-border-radius-topright: 3px; - -moz-border-radius-bottomright: 3px; - -webkit-border-top-right-radius: 3px; - -webkit-border-bottom-right-radius: 3px; -} -input[type="submit"]:hover { - color: {{ theme_white }}; - background-color: {{ theme_green_highlight }}; -} - -div.sphinxsidebar p.searchtip { - clear: both; - padding: 0.5em 0 0 0; - background: {{ theme_dirtier_white }}; - color: {{ theme_gray }}; - font-size: 0.9em; -} - -/* Sidebar links are unusual */ -div.sphinxsidebar li a, -div.sphinxsidebar p a { - background: {{ theme_light_color }}; /* In case links overlap main content */ - border-radius: 3px; - -moz-border-radius: 3px; - -webkit-border-radius: 3px; - border: 1px solid transparent; /* To prevent things jumping around on hover */ - padding: 0 5px 0 5px; -} -div.sphinxsidebar li a:hover, -div.sphinxsidebar p a:hover { - color: {{ theme_black }}; - text-decoration: none; - border: 1px solid {{ theme_light_gray }}; -} - -/* Tweak any link appearing in a heading */ -div.sphinxsidebar h3 a { -} - - - - -/* OTHER STUFF ------------------------------------------------------------ */ - -cite, code, tt { - font-family: 'Consolas', 'Deja Vu Sans Mono', - 'Bitstream Vera Sans Mono', monospace; - font-size: 0.95em; - letter-spacing: 0.01em; -} - -tt { - background-color: {{ theme_code_background }}; - color: {{ theme_dark_gray }}; -} - -tt.descname, tt.descclassname, tt.xref { - border: 0; -} - -hr { - border: 1px solid {{ theme_ruler }}; - margin: 2em; -} - -pre, #_fontwidthtest { - font-family: 'Consolas', 'Deja Vu Sans Mono', - 'Bitstream Vera Sans Mono', monospace; - margin: 1em 2em; - font-size: 0.95em; - letter-spacing: 0.015em; - line-height: 120%; - padding: 0.5em; - border: 1px solid {{ theme_lighter_gray }}; - background-color: {{ theme_code_background }}; - border-radius: 6px; - -moz-border-radius: 6px; - -webkit-border-radius: 6px; -} - -pre a { - color: inherit; - text-decoration: underline; -} - -td.linenos pre { - padding: 0.5em 0; -} - -div.quotebar { - background-color: {{ theme_almost_white }}; - max-width: 250px; - float: right; - padding: 2px 7px; - border: 1px solid {{ theme_lighter_gray }}; -} - -div.topic { - background-color: {{ theme_almost_white }}; -} - -table { - border-collapse: collapse; - margin: 0 -0.5em 0 -0.5em; -} - -table td, table th { - padding: 0.2em 0.5em 0.2em 0.5em; -} - - -/* ADMONITIONS AND WARNINGS ------------------------------------------------- */ - -/* Shared by admonitions, warnings and sidebars */ -div.admonition, -div.warning, -div.sidebar { - font-size: 0.9em; - margin: 2em; - padding: 0; - /* - border-radius: 6px; - -moz-border-radius: 6px; - -webkit-border-radius: 6px; - */ -} -div.admonition p, -div.warning p, -div.sidebar p { - margin: 0.5em 1em 0.5em 1em; - padding: 0; -} -div.admonition pre, -div.warning pre, -div.sidebar pre { - margin: 0.4em 1em 0.4em 1em; -} -div.admonition p.admonition-title, -div.warning p.admonition-title, -div.sidebar p.sidebar-title { - margin: 0; - padding: 0.1em 0 0.1em 0.5em; - color: white; - font-weight: bold; - font-size: 1.1em; - text-shadow: 0 1px rgba(0, 0, 0, 0.5); -} -div.admonition ul, div.admonition ol, -div.warning ul, div.warning ol, -div.sidebar ul, div.sidebar ol { - margin: 0.1em 0.5em 0.5em 3em; - padding: 0; -} - - -/* Admonitions and sidebars only */ -div.admonition, div.sidebar { - border: 1px solid {{ theme_positive_dark }}; - background-color: {{ theme_positive_light }}; -} -div.admonition p.admonition-title, -div.sidebar p.sidebar-title { - background-color: {{ theme_positive_medium }}; - border-bottom: 1px solid {{ theme_positive_dark }}; -} - - -/* Warnings only */ -div.warning { - border: 1px solid {{ theme_negative_dark }}; - background-color: {{ theme_negative_light }}; -} -div.warning p.admonition-title { - background-color: {{ theme_negative_medium }}; - border-bottom: 1px solid {{ theme_negative_dark }}; -} - - -/* Sidebars only */ -div.sidebar { - max-width: 200px; -} - - - -div.versioninfo { - margin: 1em 0 0 0; - border: 1px solid {{ theme_lighter_gray }}; - background-color: {{ theme_light_medium_color }}; - padding: 8px; - line-height: 1.3em; - font-size: 0.9em; -} - -.viewcode-back { - font-family: 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva', - 'Verdana', sans-serif; -} - -div.viewcode-block:target { - background-color: {{ theme_viewcode_bg }}; - border-top: 1px solid {{ theme_viewcode_border }}; - border-bottom: 1px solid {{ theme_viewcode_border }}; -} - -dl { - margin: 1em 0 2.5em 0; -} - -/* Highlight target when you click an internal link */ -dt:target { - background: {{ theme_highlight }}; -} -/* Don't highlight whole divs */ -div.highlight { - background: transparent; -} -/* But do highlight spans (so search results can be highlighted) */ -span.highlight { - background: {{ theme_highlight }}; -} - -div.footer { - background-color: {{ theme_background }}; - color: {{ theme_background_text }}; - padding: 0 2em 2em 2em; - clear: both; - font-size: 0.8em; - text-align: center; -} - -p { - margin: 0.8em 0 0.5em 0; -} - -.section p img { - margin: 1em 2em; -} - - -/* MOBILE LAYOUT -------------------------------------------------------------- */ - -@media screen and (max-width: 600px) { - - h1, h2, h3, h4, h5 { - position: relative; - } - - ul { - padding-left: 1.75em; - } - - div.bodywrapper a.headerlink, #indices-and-tables h1 a { - color: {{ theme_almost_dirty_white }}; - font-size: 80%; - float: right; - line-height: 1.8; - position: absolute; - right: -0.7em; - visibility: inherit; - } - - div.bodywrapper h1 a.headerlink, #indices-and-tables h1 a { - line-height: 1.5; - } - - pre { - font-size: 0.7em; - overflow: auto; - word-wrap: break-word; - white-space: pre-wrap; - } - - div.related ul { - height: 2.5em; - padding: 0; - text-align: left; - } - - div.related ul li { - clear: both; - color: {{ theme_dark_color }}; - padding: 0.2em 0; - } - - div.related ul li:last-child { - border-bottom: 1px dotted {{ theme_medium_color }}; - padding-bottom: 0.4em; - margin-bottom: 1em; - width: 100%; - } - - div.related ul li a { - color: {{ theme_dark_color }}; - padding-right: 0; - } - - div.related ul li a:hover { - background: inherit; - color: inherit; - } - - div.related ul li.right { - clear: none; - padding: 0.65em 0; - margin-bottom: 0.5em; - } - - div.related ul li.right a { - color: {{ theme_white }}; - padding-right: 0.8em; - } - - div.related ul li.right a:hover { - background-color: {{ theme_medium_color }}; - } - - div.body { - clear: both; - min-width: 0; - word-wrap: break-word; - } - - div.bodywrapper { - margin: 0 0 0 0; - } - - div.sphinxsidebar { - float: none; - margin: 0; - width: auto; - } - - div.sphinxsidebar input[type="text"] { - height: 2em; - line-height: 2em; - width: 70%; - } - - div.sphinxsidebar input[type="submit"] { - height: 2em; - margin-left: 0.5em; - width: 20%; - } - - div.sphinxsidebar p.searchtip { - background: inherit; - margin-bottom: 1em; - } - - div.sphinxsidebar ul li, div.sphinxsidebar p.topless { - white-space: normal; - } - - .bodywrapper img { - display: block; - margin-left: auto; - margin-right: auto; - max-width: 100%; - } - - div.documentwrapper { - float: none; - } - - div.admonition, div.warning, pre, blockquote { - margin-left: 0em; - margin-right: 0em; - } - - .body p img { - margin: 0; - } - - #searchbox { - background: transparent; - } - - .related:not(:first-child) li { - display: none; - } - - .related:not(:first-child) li.right { - display: block; - } - - div.footer { - padding: 1em; - } - - .rtd_doc_footer .badge { - float: none; - margin: 1em auto; - position: static; - } - - .rtd_doc_footer .badge.revsys-inline { - margin-right: auto; - margin-bottom: 2em; - } - - table.indextable { - display: block; - width: auto; - } - - .indextable tr { - display: block; - } - - .indextable td { - display: block; - padding: 0; - width: auto !important; - } - - .indextable td dt { - margin: 1em 0; - } - - ul.search { - margin-left: 0.25em; - } - - ul.search li div.context { - font-size: 90%; - line-height: 1.1; - margin-bottom: 1; - margin-left: 0; - } - -}
diff --git a/docs/source/_themes/armstrong/theme.conf b/docs/source/_themes/armstrong/theme.conf deleted file mode 100644 index 5930488..0000000 --- a/docs/source/_themes/armstrong/theme.conf +++ /dev/null
@@ -1,65 +0,0 @@ -[theme] -inherit = default -stylesheet = rtd.css -pygment_style = default -show_sphinx = False - -[options] -show_rtd = True - -white = #ffffff -almost_white = #f8f8f8 -barely_white = #f2f2f2 -dirty_white = #eeeeee -almost_dirty_white = #e6e6e6 -dirtier_white = #dddddd -lighter_gray = #cccccc -gray_a = #aaaaaa -gray_9 = #999999 -light_gray = #888888 -gray_7 = #777777 -gray = #666666 -dark_gray = #444444 -gray_2 = #222222 -black = #111111 -light_color = #e8ecef -light_medium_color = #DDEAF0 -medium_color = #8ca1af -medium_color_link = #86989b -medium_color_link_hover = #a6b8bb -dark_color = #465158 - -h1 = #000000 -h2 = #465158 -h3 = #6c818f - -link_color = #444444 -link_color_decoration = #CCCCCC - -medium_color_hover = #697983 -green_highlight = #8ecc4c - - -positive_dark = #609060 -positive_medium = #70a070 -positive_light = #e9ffe9 - -negative_dark = #900000 -negative_medium = #b04040 -negative_light = #ffe9e9 -negative_text = #c60f0f - -ruler = #abc - -viewcode_bg = #f4debf -viewcode_border = #ac9 - -highlight = #ffe080 - -code_background = #eeeeee - -background = #465158 -background_link = #ffffff -background_link_half = #ffffff -background_text = #eeeeee -background_text_link = #86989b
diff --git a/docs/source/about.rst b/docs/source/about.rst new file mode 100644 index 0000000..6a6068b --- /dev/null +++ b/docs/source/about.rst
@@ -0,0 +1,46 @@ +.. _chapter-about: + +===== +About +===== + +Ceres Solver grew out of the need for general least squares solving at Google. +Around 2010, Sameer Agarwal and Keir Mierle decided to replace a custom bundle +adjuster at Google with something more modern. After two years of on-and-off +development, Ceres Solver was released as open source in May of 2012. + +Acknowledgements +---------------- + +A number of people have helped with the development and open sourcing +of Ceres. + +Fredrik Schaffalitzky when he was at Google started the development of +Ceres, and even though much has changed since then, many of the ideas +from his original design are still present in the current code. + +Amongst Ceres' users at Google two deserve special mention: William +Rucklidge and James Roseborough. William was the first user of +Ceres. He bravely took on the task of porting production code to an +as-yet unproven optimization library, reporting bugs and helping fix +them along the way. James is perhaps the most sophisticated user of +Ceres at Google. He has reported and fixed bugs and helped evolve the +API for the better. + +Since the initial release of Ceres, a number of people have +contributed to Ceres by porting it to new platforms, reporting bugs, +fixing bugs and adding new functionality. We acknowledge all of these +contributions in the :ref:`chapter-version-history`. + +Origin of the name Ceres Solver +------------------------------- +While there is some debate as to who invented the method of Least Squares +[Stigler]_, there is no debate that it was `Carl Friedrich Gauss +<http://en.wikipedia.org/wiki/Carl_Friedrich_Gauss>`_ who brought it to the +attention of the world. Using just 22 observations of the newly discovered +asteroid `Ceres <http://en.wikipedia.org/wiki/Ceres_(dwarf_planet)>`_, Gauss +used the method of least squares to correctly predict when and where the +asteroid will emerge from behind the Sun [TenenbaumDirector]_. We named our +solver after Ceres to celebrate this seminal event in the history of astronomy, +statistics and optimization. +
diff --git a/docs/source/acknowledgements.rst b/docs/source/acknowledgements.rst deleted file mode 100644 index 36c1562..0000000 --- a/docs/source/acknowledgements.rst +++ /dev/null
@@ -1,25 +0,0 @@ -.. _chapter-acknowledgements: - -================ -Acknowledgements -================ - -A number of people have helped with the development and open sourcing -of Ceres. - -Fredrik Schaffalitzky when he was at Google started the development of -Ceres, and even though much has changed since then, many of the ideas -from his original design are still present in the current code. - -Amongst Ceres' users at Google two deserve special mention: William -Rucklidge and James Roseborough. William was the first user of -Ceres. He bravely took on the task of porting production code to an -as-yet unproven optimization library, reporting bugs and helping fix -them along the way. James is perhaps the most sophisticated user of -Ceres at Google. He has reported and fixed bugs and helped evolve the -API for the better. - -Since the initial release of Ceres, a number of people have -contributed to Ceres by porting it to new platforms, reporting bugs, -fixing bugs and adding new functionality. We acknowledge all of these -contributions in the :ref:`chapter-version-history`.
diff --git a/docs/source/building.rst b/docs/source/building.rst index 67045ac..750ecef 100644 --- a/docs/source/building.rst +++ b/docs/source/building.rst
@@ -1,8 +1,8 @@ .. _chapter-building: -============ -Installation -============ +===================== +Building & Installing +===================== Stable Ceres Solver releases are available for download at `code.google.com <http://code.google.com/p/ceres-solver/>`_. For the
diff --git a/docs/source/conf.py b/docs/source/conf.py index 403720f..dfe808a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py
@@ -41,7 +41,7 @@ # General information about the project. project = u'Ceres Solver' -copyright = u'2013, Google Inc.' +copyright = u'2014 Google Inc' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -91,7 +91,8 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'armstrong' +#html_theme = 'flask' +html_theme = 'sphinx_rtd_theme' # 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 @@ -100,6 +101,8 @@ # Add any paths that contain custom themes here, relative to this directory. html_theme_path = ["_themes",] +import sphinx_rtd_theme +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # The name for this set of Sphinx documents. If None, it defaults to # "<project> v<release> documentation". @@ -120,7 +123,7 @@ # 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'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format.
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index 20fe34d..876c50e 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst
@@ -1,9 +1,8 @@ .. _chapter-contributing: -============= -Contributions -============= - +============ +Contributing +============ We welcome contributions to Ceres, whether they are new features, bug fixes or tests. The Ceres `mailing
diff --git a/docs/source/faqs.rst b/docs/source/faqs.rst index a68ba77..3dee336 100644 --- a/docs/source/faqs.rst +++ b/docs/source/faqs.rst
@@ -267,3 +267,13 @@ Total 0.998 The preprocessor time has gone down by more than 4x!. + +Further Reading +=============== + +For a short but informative introduction to the subject we recommend +the booklet by [Madsen]_ . For a general introduction to non-linear +optimization we recommend [NocedalWright]_. [Bjorck]_ remains the +seminal reference on least squares problems. [TrefethenBau]_ book is +our favorite text on introductory numerical linear algebra. [Triggs]_ +provides a thorough coverage of the bundle adjustment problem.
diff --git a/docs/source/index.rst b/docs/source/index.rst index 62d4c0b..6ac00da 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst
@@ -7,35 +7,8 @@ Ceres Solver ============ -Ceres Solver is a portable C++ library for solving non-linear least -squares problems. - -* Download the latest stable `release - <https://ceres-solver.googlecode.com/files/ceres-solver-1.8.0.tar.gz>`_ - or clone the `repository - <https://ceres-solver.googlesource.com/ceres-solver>`_ - -* Read the :ref:`chapter-tutorial` - -* Browse the :ref:`chapter-modeling` API and :ref:`chapter-solving` API. - -* Join the `mailing list - <https://groups.google.com/forum/?fromgroups#!forum/ceres-solver>`_ - and ask questions. - -* File bugs, feature requests in the `issue tracker - <https://code.google.com/p/ceres-solver/issues/list>`_. - -* If you use Ceres Solver for a publication, you must cite it as:: - - @misc{ceres-solver, - author = "Sameer Agarwal and Keir Mierle and Others", - title = "Ceres Solver", - howpublished = "\url{https://code.google.com/p/ceres-solver/}", - } - .. toctree:: - :maxdepth: 1 + :maxdepth: 3 :hidden: introduction @@ -44,9 +17,71 @@ modeling solving faqs - reading contributing - acknowledgements version_history + about bibliography license + +Solving `nonlinear least squares`_ problems comes up in a broad range of areas +across science and engineering - from `fitting curves`_ in statistics, to +constructing `3D models from photographs`_ in computer vision. + +.. _nonlinear least squares: http://en.wikipedia.org/wiki/Non-linear_least_squares +.. _fitting curves: http://en.wikipedia.org/wiki/Nonlinear_regression +.. _3D models from photographs: http://en.wikipedia.org/wiki/Structure_from_motion + +What is Ceres Solver? +--------------------- +Ceres is an industrial-grade C++ library for modeling and solving large and +small nonlinear least squares problems of the form + +.. math:: \frac{1}{2}\sum_{i} \rho_i\left(\left\|f_i\left(x_{i_1}, ... ,x_{i_k}\right)\right\|^2\right). + +For a brief introduction to nonlinear solving in general, see the +:ref:`chapter-tutorial`. + +Who uses Ceres Solver? +---------------------- +There are many users of Ceres, including Google Street View, Google Maps, +several SLAM pipelines, Blender, and more. See the :ref:`chapter-introduction` +for more users. + +Why use Ceres Solver? +--------------------- +Ceres is a world-class least squares solver for a variety of reasons, including +an integrated modelling layer, automatic differentiation, optimized code, +extensive tests, and more. See the :ref:`chapter-introduction` for a detailed +list. + +Getting started +--------------- + +* Download the `latest stable release + <http://ceres-solver.org/ceres-solver-1.8.0.tar.gz>`_ + or, for those wanting the latest +* Clone the development version or `browse the source + <https://ceres-solver.googlesource.com/ceres-solver>`_ + + .. code-block:: bash + + git clone https://ceres-solver.googlesource.com/ceres-solver + +* Read the :ref:`chapter-tutorial` +* Browse the :ref:`chapter-modeling` and :ref:`chapter-solving`. +* Join the `mailing list + <https://groups.google.com/forum/?fromgroups#!forum/ceres-solver>`_ + and ask questions. +* File bugs, feature requests in the `issue tracker + <https://code.google.com/p/ceres-solver/issues/list>`_. +* Improve Ceres by :ref:`chapter-contributing` + +Cite Us +------- +If you use Ceres Solver for a publication, you must cite it as:: + + @misc{ceres-solver, + author = "Sameer Agarwal and Keir Mierle and Others", + title = "Ceres Solver", + howpublished = "\url{http://ceres-solver.org}", + }
diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index 19a6f2e..72625c8 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst
@@ -4,78 +4,68 @@ Introduction ============ -Solving nonlinear least squares problems [#f1]_ comes up in a broad -range of areas across science and engineering - from fitting curves in -statistics, to constructing 3D models from photographs in computer -vision. Ceres Solver [#f2]_ [#f3]_ is a portable C++ library for -solving non-linear least squares problems accurately and efficiently. +What is Ceres Solver? +--------------------- +Ceres is an industrial-grade C++ library for modeling and solving large and +small nonlinear least squares problems of the form -**Features** +.. math:: \frac{1}{2}\sum_{i} \rho_i\left(\left\|f_i\left(x_{i_1}, ... ,x_{i_k}\right)\right\|^2\right). -#. A friendly :ref:`chapter-modeling` API. +For a brief introduction to nonlinear solving in general, see the +:ref:`chapter-tutorial`. -#. Automatic and numeric differentiation. +Who uses Ceres Solver? +---------------------- -#. Robust loss functions and local parameterizations. +* `Google Street View`_ panorama poses are computed with Ceres (`see video`_) +* `Google Photo Tours`_ employ Ceres to pose all the photos +* `Google Maps and Earth`_ imagery spatial alignment and satellite sensor calibration is done with Ceres +* `Project Tango`_ uses Ceres as part of the SLAM pipeline +* `Willow Garage's`_ SLAM pipeline uses Ceres for realtime bundle adjustment +* `Android`_ uses Ceres for image processing and stitching, including for `Photo Sphere`_ +* `Blender's`_ `motion tracking module`_ depends critically on Ceres, using it + for 2D tracking, 3D reconstruction, panorama tracking, plane tracking, and + more; see the results in `Tears of Steel`_ -#. Multithreading. +.. _Google Street View: http://www.google.com/maps/about/behind-the-scenes/streetview/ +.. _see video: https://www.youtube.com/watch?v=z00ORu4bU-A +.. _Google Photo Tours: http://googlesystem.blogspot.com/2012/04/photo-tours-in-google-maps.html +.. _Google Maps and Earth: http://www.google.com/earth/ +.. _Project Tango: https://www.google.com/atap/projecttango/ +.. _Willow Garage's: https://www.willowgarage.com/blog/2013/08/09/enabling-robots-see-better-through-improved-camera-calibration +.. _Android: https://android.googlesource.com/platform/external/ceres-solver/ +.. _Photo Sphere: http://www.google.com/maps/about/contribute/photosphere/ +.. _Blender's: http://blender.org +.. _motion tracking module: http://wiki.blender.org/index.php/Doc:2.6/Manual/Motion_Tracking +.. _Tears of Steel: http://mango.blender.org/ -#. Trust-Region (Levenberg-Marquardt and Dogleg) and Line Search - (Nonlinear CG and L-BFGS) solvers. +Why use Ceres Solver? +--------------------- +* Ceres has an **integrated modelling layer**, making it easy and intutive to + model large, complex cost functions with interacting terms, such as a moving + vehicle with multiple sensors and tricky dynamics +* Ceres has **integrated automatic differentiation**, avoiding the error-prone + task of manually computing derivatives +* Ceres can model a **wide variety of problems**, beyond simple nonlinear least + squares, thanks to robust loss functions and local parameterizations (e.g. + for quaternions) +* Ceres is **very fast**, thanks to threaded cost function evaluators, threaded linear + solvers, and generous amounts of engineering time spent optimizing +* Ceres has **multiple nonlinear solvers** including trust region (fast, uses + more memory) and line search (slower, uses less memory) +* Ceres has **multiple linear solvers** for both sparse and dense systems, + leveraging Eigen or MKL for dense solving, CHOLMOD or CXSparse for sparse + solving, and specialized linear solvers bundle adjustment +* Ceres has **thorough automated tests** ensuring it is high-quality +* Ceres is **industrial grade** thanks to **many compute-years** spent + running its code, analyzing the results, and improving it +* Ceres has **world-class solution quality**, with the best known results of + any least squares solver on the `NIST least squares precision benchmark`_ +* Ceres has an **active community** encouraging contributions and mentoring + those starting out +* Ceres runs on **many platforms** including Linux, Windows, Mac OS X, Android, and + iOS (sort of) +* Ceres is **liberally licensed (BSD)** so that you can use it freely in + commercial applications without releasing your code -#. Variety of linear solvers. - - a. Dense QR and Cholesky factorization (using `Eigen - <http://eigen.tuxfamily.org/index.php?title=Main_Page>`_) for - small problems. - - b. Sparse Cholesky factorization (using `SuiteSparse - <http://www.cise.ufl.edu/research/sparse/SuiteSparse/>`_ and - `CXSparse <http://www.cise.ufl.edu/research/sparse/CSparse/>`_) for - large sparse problems. - - c. Specialized solvers for bundle adjustment problems in computer - vision. - - d. Iterative linear solvers with preconditioners for general sparse - and bundle adjustment problems. - -#. Portable: Runs on Linux, Windows, Mac OS X and Android. - - -At Google, Ceres Solver has been used for solving a variety of -problems in computer vision and machine learning. e.g., it is used to -to estimate the pose of Street View cars, aircrafts, and satellites; -to build 3D models for PhotoTours; to estimate satellite image sensor -characteristics, and more. - -`Blender <http://www.blender.org>`_ uses Ceres for `motion tracking -<http://mango.blender.org/development/planar-tracking-preview/>`_ and -`bundle adjustment -<http://wiki.blender.org/index.php/Dev:Ref/Release_Notes/2.67/Motion_Tracker>`_. - - -.. rubric:: Footnotes - -.. [#f1] For a gentle but brief introduction to non-linear least - squares problems, please start by reading the - :ref:`chapter-tutorial`. - -.. [#f2] While there is some debate as to who invented the method of - Least Squares [Stigler]_, there is no debate that it was - `Carl Friedrich Gauss - <http://en.wikipedia.org/wiki/Carl_Friedrich_Gauss>`_ who - brought it to the attention of the world. Using just 22 - observations of the newly discovered asteroid `Ceres - <http://en.wikipedia.org/wiki/Ceres_(dwarf_planet)>`_, Gauss - used the method of least squares to correctly predict when - and where the asteroid will emerge from behind the Sun - [TenenbaumDirector]_. We named our solver after Ceres to - celebrate this seminal event in the history of astronomy, - statistics and optimization. - -.. [#f3] For brevity, in the rest of this document we will just use - the term Ceres. - - - +.. _NIST least squares precision benchmark: https://groups.google.com/forum/#!topic/ceres-solver/UcicgMPgbXw
diff --git a/docs/source/license.rst b/docs/source/license.rst index 58d70df..cfa1d79 100644 --- a/docs/source/license.rst +++ b/docs/source/license.rst
@@ -4,7 +4,7 @@ Ceres Solver is licensed under the New BSD license, whose terms are as follows. -Copyright (c) 2010, 2011, 2012, 2013 Google Inc. All rights reserved. +Copyright (c) 2014 Google Inc. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
diff --git a/docs/source/modeling.rst b/docs/source/modeling.rst index f06ef0d..4460174 100644 --- a/docs/source/modeling.rst +++ b/docs/source/modeling.rst
@@ -4,9 +4,9 @@ .. _`chapter-modeling`: -======== -Modeling -======== +============ +Modeling API +============ Recall that Ceres solves robustified non-linear least squares problems of the form
diff --git a/docs/source/reading.rst b/docs/source/reading.rst deleted file mode 100644 index 4e27567..0000000 --- a/docs/source/reading.rst +++ /dev/null
@@ -1,10 +0,0 @@ -=============== -Further Reading -=============== - -For a short but informative introduction to the subject we recommend -the booklet by [Madsen]_ . For a general introduction to non-linear -optimization we recommend [NocedalWright]_. [Bjorck]_ remains the -seminal reference on least squares problems. [TrefethenBau]_ book is -our favorite text on introductory numerical linear algebra. [Triggs]_ -provides a thorough coverage of the bundle adjustment problem.
diff --git a/docs/source/solving.rst b/docs/source/solving.rst index fcc3c4c..1e11c4a 100644 --- a/docs/source/solving.rst +++ b/docs/source/solving.rst
@@ -5,10 +5,9 @@ .. _chapter-solving: -======= -Solving -======= - +=========== +Solving API +=========== Introduction ============
diff --git a/docs/source/version_history.rst b/docs/source/version_history.rst index 6752b15..ecc1ce2 100644 --- a/docs/source/version_history.rst +++ b/docs/source/version_history.rst
@@ -1,8 +1,8 @@ .. _chapter-version-history: -=============== -Version History -=============== +======== +Releases +======== 1.8.0 =====