Add theme for inclusion of the documentation on the website

This commit is contained in:
Sylvain Lebresne 2016-07-13 15:50:36 +02:00
parent 47d3b7e7a0
commit 7eb9531a4d
10 changed files with 286 additions and 62 deletions

View File

@ -724,6 +724,10 @@
</copy>
</target>
<target name="echo-base-version">
<echo message="${base.version}" />
</target>
<!--
Generate thrift code. We have targets to build java because
Cassandra depends on it, and python because that is what the system

View File

@ -19,10 +19,13 @@ YAML_DOC_OUTPUT=source/configuration/cassandra_config_file.rst
MAKE_CASSANDRA_YAML = python convert_yaml_to_rst.py $(YAML_DOC_INPUT) $(YAML_DOC_OUTPUT)
WEB_SITE_PRESENCE_FILE='source/.build_for_website'
.PHONY: help
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " website to make HTML files for the Cassandra website"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@ -61,6 +64,15 @@ html:
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
.PHONY: website
website: clean
@touch $(WEB_SITE_PRESENCE_FILE)
$(MAKE_CASSANDRA_YAML)
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@rm $(WEB_SITE_PRESENCE_FILE)
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
.PHONY: dirhtml
dirhtml:
$(MAKE_CASSANDRA_YAML)

View File

@ -3,34 +3,64 @@
<div id="wipwarning">This documentation is currently a work-in-progress and contains a number of TODO sections.
<a href="{{ pathto("bugs") }}">Contributions</a> are welcome.</div>
<p><strong>{% trans %}Main documentation parts:{% endtrans %}</strong></p>
<table class="contentstable" align="center"><tr>
<td width="50%">
<h3>Main documentation</h3>
<table class="contentstable doc-landing-table" align="center">
<tr>
<td class="left-column">
<p class="biglink"><a class="biglink" href="{{ pathto("getting_started/index") }}">{% trans %}Getting started{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}Newbie friendly starting point{% endtrans %}</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("architecture/index") }}">{% trans %}Cassandra Architecture{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}Cassandra's big picture{% endtrans %}</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("data_modeling/index") }}">{% trans %}Data Modeling{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}Or how to make square pegs fit round holes{% endtrans %}</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("cql/index") }}">{% trans %}Cassandra Query Language{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}CQL reference documentation{% endtrans %}</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("configuration/index") }}">{% trans %}Configuration{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}Cassandra's handles and knobs{% endtrans %}</span></p>
</td><td width="50%" class="rightcolumn">
<span class="linkdescr">{% trans %}Newbie friendly starting point{% endtrans %}</span></p>
</td>
<td class="right-column">
<p class="biglink"><a class="biglink" href="{{ pathto("operating/index") }}">{% trans %}Operating Cassandra{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}The operator's corner{% endtrans %}</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("tooling/index") }}">{% trans %}Cassandra's Tools{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}cqlsh, nodetool, ...{% endtrans %}</span></p>
<span class="linkdescr">{% trans %}The operator's corner{% endtrans %}</span></p>
</td>
</tr>
<tr>
<td class="left-column">
<p class="biglink"><a class="biglink" href="{{ pathto("architecture/index") }}">{% trans %}Cassandra Architecture{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}Cassandra's big picture{% endtrans %}</span></p>
</td>
<td class="right-column">
<p class="biglink"><a class="biglink" href="{{ pathto("tools/index") }}">{% trans %}Cassandra's Tools{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}cqlsh, nodetool, ...{% endtrans %}</span></p>
</td>
</tr>
<tr>
<td class="left-column">
<p class="biglink"><a class="biglink" href="{{ pathto("data_modeling/index") }}">{% trans %}Data Modeling{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}Or how to make square pegs fit round holes{% endtrans %}</span></p>
</td>
<td class="right-column">
<p class="biglink"><a class="biglink" href="{{ pathto("troubleshooting/index") }}">{% trans %}Troubleshooting{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}What to look for when you have a problem{% endtrans %}</span></p>
<span class="linkdescr">{% trans %}What to look for when you have a problem{% endtrans %}</span></p>
</td>
</tr>
<tr>
<td class="left-column">
<p class="biglink"><a class="biglink" href="{{ pathto("cql/index") }}">{% trans %}Cassandra Query Language{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}CQL reference documentation{% endtrans %}</span></p>
</td>
<td class="right-column">
<p class="biglink"><a class="biglink" href="{{ pathto("faq/index") }}">{% trans %}FAQs{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}Frequently Asked Questions (with answers!){% endtrans %}</span></p>
</td></tr>
</table>
<span class="linkdescr">{% trans %}Frequently Asked Questions (with answers!){% endtrans %}</span></p>
</td>
</tr>
<tr>
<td class="left-column">
<p class="biglink"><a class="biglink" href="{{ pathto("configuration/index") }}">{% trans %}Configuration{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}Cassandra's handles and knobs{% endtrans %}</span></p>
</td>
<td class="right-column">
</td>
</tr>
</table>
<p><strong>{% trans %}Meta informations:{% endtrans %}</strong></p>
<h3>Meta informations</h3>
<p class="biglink"><a class="biglink" href="{{ pathto("bugs") }}">{% trans %}Reporting bugs{% endtrans %}</a></p>
<p class="biglink"><a class="biglink" href="{{ pathto("contactus") }}">{% trans %}Contact us{% endtrans %}</a></p>
<ul>
<li><a class="biglink" href="{{ pathto("bugs") }}">{% trans %}Reporting bugs{% endtrans %}</a></li>
<li><a class="biglink" href="{{ pathto("contactus") }}">{% trans %}Contact us{% endtrans %}</a></li>
</ul>
{% endblock %}

View File

@ -0,0 +1,25 @@
---
layout: doclandingpage
title: "Documentation"
is_homepage: false
is_sphinx_doc: false
---
{% block body %}
<h2>{{ docstitle|e }}</h2>
{% block tables %}
<p><strong>{{ _('Indices and tables:') }}</strong></p>
<table class="contentstable" align="center"><tr>
<td width="50%">
<p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">{{ _('Complete Table of Contents') }}</a><br>
<span class="linkdescr">{{ _('lists all sections and subsections') }}</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{{ _('Search Page') }}</a><br>
<span class="linkdescr">{{ _('search this documentation') }}</span></p>
</td><td width="50%">
<p class="biglink"><a class="biglink" href="{{ pathto("modindex") }}">{{ _('Global Module Index') }}</a><br>
<span class="linkdescr">{{ _('quick access to all modules') }}</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{{ _('General Index') }}</a><br>
<span class="linkdescr">{{ _('all functions, classes, terms') }}</span></p>
</td></tr>
</table>
{% endblock %}
{% endblock %}

View File

@ -0,0 +1,95 @@
---
layout: docpage
{% block title %}
title: "Documentation"
{% endblock%}
is_homepage: false
is_sphinx_doc: true
{% for doc in parents %}
doc-parent: "{{ doc.title }}"
{% endfor %}
doc-title: "{{ title }}"
doc-header-links: '
<link rel="top" title="{{ docstitle|e }}" href="{{ pathto('index') }}"/>
{%- if parents %}
<link rel="up" title="{{ parents[-1].title|striptags|e }}" href="{{ parents[-1].link|e }}"/>
{%- endif %}
{%- if next %}
<link rel="next" title="{{ next.title|striptags|e }}" href="{{ next.link|e }}"/>
{%- endif %}
{%- if prev %}
<link rel="prev" title="{{ prev.title|striptags|e }}" href="{{ prev.link|e }}"/>
{%- endif %}
'
doc-search-path: "{{ pathto('search') }}"
{% block extrafooter %}
extra-footer: '
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: "{{ url_root }}",
VERSION: "{{ release|e }}",
COLLAPSE_INDEX: false,
FILE_SUFFIX: "{{ "" if no_search_suffix else file_suffix }}",
HAS_SOURCE: false,
SOURCELINK_SUFFIX: "{{ sourcelink_suffix }}"
};
</script>
'
{% endblock %}
---
<div class="container-fluid">
<div class="row">
<div class="col-md-2">
<div class="doc-navigation">
<div class="doc-menu" role="navigation">
<div class="navbar-header">
<button type="button" class="pull-left navbar-toggle" data-toggle="collapse" data-target=".sidebar-navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<div class="navbar-collapse collapse sidebar-navbar-collapse">
<form id="doc-search-form" class="navbar-form" action="{{ pathto('search') }}" method="get" role="search">
<div class="form-group">
<input type="text" size="30" class="form-control input-sm" name="q" placeholder="Search docs">
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</div>
</form>
{% block menu %}
{% set toctree = toctree(maxdepth=3, collapse=True, includehidden=True) %}
{% if toctree %}
{{ toctree }}
{% else %}
<!-- Local TOC -->
<div class="local-toc">{{ toc }}</div>
{% endif %}
{% endblock %}
</div><!--/.nav-collapse -->
</div>
</div>
</div>
<div class="col-md-8">
<div class="content doc-content">
<div class="container">
{% block body %}{% endblock %}
{% if next or prev %}
<div class="doc-prev-next-links" role="navigation" aria-label="footer navigation">
{% if next %}
<a href="{{ next.link|e }}" class="btn btn-default pull-right " role="button" title="{{ next.title|striptags|e }}" accesskey="n">Next <span class="glyphicon glyphicon-circle-arrow-right" aria-hidden="true"></span></a>
{% endif %}
{% if prev %}
<a href="{{ prev.link|e }}" class="btn btn-default" role="button" title="{{ prev.title|striptags|e }}" accesskey="p"><span class="glyphicon glyphicon-circle-arrow-left" aria-hidden="true"></span> Previous</a>
{% endif %}
</div>
{% endif %}
</div>
</div>
</div>
<div class="col-md-2">
</div>
</div>
</div>

View File

@ -0,0 +1,53 @@
{%- extends "layout.html" %}
{% block title %}
title: "{{_('Search')}}"
{% endblock %}
{% block extrafooter %}
extra-footer: '
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: "{{ url_root }}",
VERSION: "{{ release|e }}",
COLLAPSE_INDEX: false,
FILE_SUFFIX: "{{ "" if no_search_suffix else file_suffix }}",
HAS_SOURCE: false,
SOURCELINK_SUFFIX: "{{ sourcelink_suffix }}"
};
</script>
<script type="text/javascript">
jQuery(function() { Search.loadIndex("{{ pathto('searchindex.js', 1) }}"); });
</script>
{# this is used when loading the search index using $.ajax fails,
such as on Chrome for documents on localhost #}
<script type="text/javascript" id="searchindexloader"></script>
'
{% endblock %}
{% block body %}
<noscript>
<div id="fallback" class="admonition warning">
<p class="last">
{% trans %}Please activate JavaScript to enable the search
functionality.{% endtrans %}
</p>
</div>
</noscript>
{% if search_performed %}
<h2>{{ _('Search Results') }}</h2>
{% if not search_results %}
<p>{{ _('Your search did not match any documents. Please make sure that all words are spelled correctly.') }}</p>
{% endif %}
{% endif %}
<div id="search-results">
{% if search_results %}
<ul>
{% for href, caption, context in search_results %}
<li>
<a href="{{ pathto(item.href) }}">{{ caption }}</a>
<p class="context">{{ context|e }}</p>
</li>
{% endfor %}
</ul>
{% endif %}
</div>
{% endblock %}

View File

@ -0,0 +1,3 @@
[theme]
inherit = basic
stylesheet = none

View File

@ -37,6 +37,8 @@ def setup(sphinx):
from cql import CQLLexer
sphinx.add_lexer("cql", CQLLexer())
# Ugly way to find out if we're building for the website (the Makefile creates an empty file for us)
build_for_website = os.path.isfile('.build_for_website')
# -- General configuration ------------------------------------------------
@ -136,10 +138,11 @@ todo_include_todos = True
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
if build_for_website:
html_theme = 'cassandra_theme'
html_theme_path = ['./_theme']
else:
html_theme = 'sphinx_rtd_theme'
html_context = { 'extra_css_files': [ '_static/extra.css' ] }
@ -149,9 +152,6 @@ html_context = { 'extra_css_files': [ '_static/extra.css' ] }
#
# html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = ['.']
# The name for this set of Sphinx documents.
# "<project> v<release> documentation" by default.
#

View File

@ -14,6 +14,8 @@
.. See the License for the specific language governing permissions and
.. limitations under the License.
.. highlight:: none
Installing Cassandra
--------------------

View File

@ -65,10 +65,10 @@ The metric names are all appended with the specific ``Keyspace`` and ``Table`` n
Reported name format:
**Metric Name**
``org.apache.cassandra.metrics.Table.{{MetricName}}.{{Keyspace}}.{{Table}}``
``org.apache.cassandra.metrics.Table.<MetricName>.<Keyspace>.<Table>``
**JMX MBean**
``org.apache.cassandra.metrics:type=Table keyspace={{Keyspace} scope={{Table}} name={{MetricName}}``
``org.apache.cassandra.metrics:type=Table keyspace=<Keyspace> scope=<Table> name=<MetricName>``
.. NOTE::
There is a special table called '``all``' without a keyspace. This represents the aggregation of metrics across
@ -140,10 +140,10 @@ These metrics are the same as the ``Table Metrics`` above, only they are aggrega
Reported name format:
**Metric Name**
``org.apache.cassandra.metrics.keyspace.{{MetricName}}.{{Keyspace}}``
``org.apache.cassandra.metrics.keyspace.<MetricName>.<Keyspace>``
**JMX MBean**
``org.apache.cassandra.metrics:type=Keyspace scope={{Keyspace}} name={{MetricName}}``
``org.apache.cassandra.metrics:type=Keyspace scope=<Keyspace> name=<MetricName>``
ThreadPool Metrics
^^^^^^^^^^^^^^^^^^
@ -158,10 +158,10 @@ specific type.
Reported name format:
**Metric Name**
``org.apache.cassandra.metrics.ThreadPools.{{MetricName}}.{{Path}}.{{ThreadPoolName}}``
``org.apache.cassandra.metrics.ThreadPools.<MetricName>.<Path>.<ThreadPoolName>``
**JMX MBean**
``org.apache.cassandra.metrics:type=ThreadPools scope={{ThreadPoolName}} type={{Type}} name={{MetricName}}``
``org.apache.cassandra.metrics:type=ThreadPools scope=<ThreadPoolName> type=<Type> name=<MetricName>``
===================== ============== ===========
Name Type Description
@ -216,10 +216,10 @@ Different types of client requests are broken down by ``RequestType``.
Reported name format:
**Metric Name**
``org.apache.cassandra.metrics.ClientRequest.{{MetricName}}.{{RequestType}}``
``org.apache.cassandra.metrics.ClientRequest.<MetricName>.<RequestType>``
**JMX MBean**
``org.apache.cassandra.metrics:type=ClientRequest scope={{RequestType}} name={{MetricName}}``
``org.apache.cassandra.metrics:type=ClientRequest scope=<RequestType> name=<MetricName>``
:RequestType: CASRead
@ -310,10 +310,10 @@ Cassandra caches have metrics to track the effectivness of the caches. Though th
Reported name format:
**Metric Name**
``org.apache.cassandra.metrics.Cache.{{MetricName}}.{{CacheName}}``
``org.apache.cassandra.metrics.Cache.<MetricName>.<CacheName>``
**JMX MBean**
``org.apache.cassandra.metrics:type=Cache scope={{CacheName}} name={{MetricName}}``
``org.apache.cassandra.metrics:type=Cache scope=<CacheName> name=<MetricName>``
========================== ============== ===========
Name Type Description
@ -353,10 +353,10 @@ Metrics specific to CQL prepared statement caching.
Reported name format:
**Metric Name**
``org.apache.cassandra.metrics.CQL.{{MetricName}}``
``org.apache.cassandra.metrics.CQL.<MetricName>``
**JMX MBean**
``org.apache.cassandra.metrics:type=CQL name={{MetricName}}``
``org.apache.cassandra.metrics:type=CQL name=<MetricName>``
========================== ============== ===========
Name Type Description
@ -378,10 +378,10 @@ Dropped writes are stored and retried by ``Hinted Handoff``
Reported name format:
**Metric Name**
``org.apache.cassandra.metrics.DroppedMessages.{{MetricName}}.{{Type}}``
``org.apache.cassandra.metrics.DroppedMessages.<MetricName>.<Type>``
**JMX MBean**
``org.apache.cassandra.metrics:type=DroppedMetrics scope={{Type}} name={{MetricName}}``
``org.apache.cassandra.metrics:type=DroppedMetrics scope=<Type> name=<MetricName>``
========================== ============== ===========
Name Type Description
@ -419,10 +419,10 @@ These metrics are specific to a peer endpoint, with the source node being the no
Reported name format:
**Metric Name**
``org.apache.cassandra.metrics.Streaming.{{MetricName}}.{{PeerIP}}``
``org.apache.cassandra.metrics.Streaming.<MetricName>.<PeerIP>``
**JMX MBean**
``org.apache.cassandra.metrics:type=Streaming scope={{PeerIP}} name={{MetricName}}``
``org.apache.cassandra.metrics:type=Streaming scope=<PeerIP> name=<MetricName>``
========================== ============== ===========
Name Type Description
@ -440,10 +440,10 @@ Metrics specific to ``Compaction`` work.
Reported name format:
**Metric Name**
``org.apache.cassandra.metrics.Compaction.{{MetricName}}``
``org.apache.cassandra.metrics.Compaction.<MetricName>``
**JMX MBean**
``org.apache.cassandra.metrics:type=Compaction name={{MetricName}}``
``org.apache.cassandra.metrics:type=Compaction name=<MetricName>``
========================== ======================================== ===============================================
Name Type Description
@ -463,10 +463,10 @@ Metrics specific to the ``CommitLog``
Reported name format:
**Metric Name**
``org.apache.cassandra.metrics.CommitLog.{{MetricName}}``
``org.apache.cassandra.metrics.CommitLog.<MetricName>``
**JMX MBean**
``org.apache.cassandra.metrics:type=CommitLog name={{MetricName}}``
``org.apache.cassandra.metrics:type=CommitLog name=<MetricName>``
========================== ============== ===========
Name Type Description
@ -486,10 +486,10 @@ Metrics specific to the storage engine.
Reported name format:
**Metric Name**
``org.apache.cassandra.metrics.Storage.{{MetricName}}``
``org.apache.cassandra.metrics.Storage.<MetricName>``
**JMX MBean**
``org.apache.cassandra.metrics:type=Storage name={{MetricName}}``
``org.apache.cassandra.metrics:type=Storage name=<MetricName>``
========================== ============== ===========
Name Type Description
@ -510,16 +510,16 @@ These metrics include the peer endpoint **in the metric name**
Reported name format:
**Metric Name**
``org.apache.cassandra.metrics.HintedHandOffManager.{{MetricName}}``
``org.apache.cassandra.metrics.HintedHandOffManager.<MetricName>``
**JMX MBean**
``org.apache.cassandra.metrics:type=HintedHandOffManager name={{MetricName}}``
``org.apache.cassandra.metrics:type=HintedHandOffManager name=<MetricName>``
=========================== ============== ===========
Name Type Description
=========================== ============== ===========
Hints_created-{{PeerIP}} Counter Number of hints on disk for this peer.
Hints_not_stored-{{PeerIP}} Counter Number of hints not stored for this peer, due to being down past the configured hint window.
Hints_created-<PeerIP> Counter Number of hints on disk for this peer.
Hints_not_stored-<PeerIP> Counter Number of hints not stored for this peer, due to being down past the configured hint window.
=========================== ============== ===========
SSTable Index Metrics
@ -530,10 +530,10 @@ Metrics specific to the SSTable index metadata.
Reported name format:
**Metric Name**
``org.apache.cassandra.metrics.Index.{{MetricName}}.RowIndexEntry``
``org.apache.cassandra.metrics.Index.<MetricName>.RowIndexEntry``
**JMX MBean**
``org.apache.cassandra.metrics:type=Index scope=RowIndexEntry name={{MetricName}}``
``org.apache.cassandra.metrics:type=Index scope=RowIndexEntry name=<MetricName>``
=========================== ============== ===========
Name Type Description
@ -552,10 +552,10 @@ lower by recycling on and off heap buffers.
Reported name format:
**Metric Name**
``org.apache.cassandra.metrics.BufferPool.{{MetricName}}``
``org.apache.cassandra.metrics.BufferPool.<MetricName>``
**JMX MBean**
``org.apache.cassandra.metrics:type=BufferPool name={{MetricName}}``
``org.apache.cassandra.metrics:type=BufferPool name=<MetricName>``
=========================== ============== ===========
Name Type Description
@ -573,10 +573,10 @@ Metrics specifc to client managment.
Reported name format:
**Metric Name**
``org.apache.cassandra.metrics.Client.{{MetricName}}``
``org.apache.cassandra.metrics.Client.<MetricName>``
**JMX MBean**
``org.apache.cassandra.metrics:type=Client name={{MetricName}}``
``org.apache.cassandra.metrics:type=Client name=<MetricName>``
=========================== ============== ===========
Name Type Description