From 7eb9531a4dc6286d9697dc8ebd75e09feec1795d Mon Sep 17 00:00:00 2001 From: Sylvain Lebresne Date: Wed, 13 Jul 2016 15:50:36 +0200 Subject: [PATCH] Add theme for inclusion of the documentation on the website --- build.xml | 4 + doc/Makefile | 12 +++ doc/source/_templates/indexcontent.html | 76 ++++++++++----- .../_theme/cassandra_theme/defindex.html | 25 +++++ doc/source/_theme/cassandra_theme/layout.html | 95 +++++++++++++++++++ doc/source/_theme/cassandra_theme/search.html | 53 +++++++++++ doc/source/_theme/cassandra_theme/theme.conf | 3 + doc/source/conf.py | 14 +-- doc/source/getting_started/installing.rst | 2 + doc/source/operating/metrics.rst | 64 ++++++------- 10 files changed, 286 insertions(+), 62 deletions(-) create mode 100644 doc/source/_theme/cassandra_theme/defindex.html create mode 100644 doc/source/_theme/cassandra_theme/layout.html create mode 100644 doc/source/_theme/cassandra_theme/search.html create mode 100644 doc/source/_theme/cassandra_theme/theme.conf diff --git a/build.xml b/build.xml index b8b470c139..20998f28d9 100644 --- a/build.xml +++ b/build.xml @@ -724,6 +724,10 @@ + + + + +
{{ toc }}
+ {% endif %} + {% endblock %} + + + + +
+
+
+ {% block body %}{% endblock %} + + {% if next or prev %} + + {% endif %} +
+
+
+
+
+ + diff --git a/doc/source/_theme/cassandra_theme/search.html b/doc/source/_theme/cassandra_theme/search.html new file mode 100644 index 0000000000..d5e26a993e --- /dev/null +++ b/doc/source/_theme/cassandra_theme/search.html @@ -0,0 +1,53 @@ +{%- extends "layout.html" %} +{% block title %} +title: "{{_('Search')}}" +{% endblock %} +{% block extrafooter %} +extra-footer: ' + + + {# this is used when loading the search index using $.ajax fails, + such as on Chrome for documents on localhost #} + +' +{% endblock %} +{% block body %} + + + {% if search_performed %} +

{{ _('Search Results') }}

+ {% if not search_results %} +

{{ _('Your search did not match any documents. Please make sure that all words are spelled correctly.') }}

+ {% endif %} + {% endif %} +
+ {% if search_results %} + + {% endif %} +
+{% endblock %} diff --git a/doc/source/_theme/cassandra_theme/theme.conf b/doc/source/_theme/cassandra_theme/theme.conf new file mode 100644 index 0000000000..42c0704b50 --- /dev/null +++ b/doc/source/_theme/cassandra_theme/theme.conf @@ -0,0 +1,3 @@ +[theme] +inherit = basic +stylesheet = none diff --git a/doc/source/conf.py b/doc/source/conf.py index 63697aa8d4..7143b23b46 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -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. # " v documentation" by default. # diff --git a/doc/source/getting_started/installing.rst b/doc/source/getting_started/installing.rst index ad0a1e806d..e96edd7fb5 100644 --- a/doc/source/getting_started/installing.rst +++ b/doc/source/getting_started/installing.rst @@ -14,6 +14,8 @@ .. See the License for the specific language governing permissions and .. limitations under the License. +.. highlight:: none + Installing Cassandra -------------------- diff --git a/doc/source/operating/metrics.rst b/doc/source/operating/metrics.rst index 5884cad3b5..2c634c4204 100644 --- a/doc/source/operating/metrics.rst +++ b/doc/source/operating/metrics.rst @@ -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...`` **JMX MBean** - ``org.apache.cassandra.metrics:type=Table keyspace={{Keyspace} scope={{Table}} name={{MetricName}}`` + ``org.apache.cassandra.metrics:type=Table keyspace= scope=
name=`` .. 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..`` **JMX MBean** - ``org.apache.cassandra.metrics:type=Keyspace scope={{Keyspace}} name={{MetricName}}`` + ``org.apache.cassandra.metrics:type=Keyspace scope= name=`` 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...`` **JMX MBean** - ``org.apache.cassandra.metrics:type=ThreadPools scope={{ThreadPoolName}} type={{Type}} name={{MetricName}}`` + ``org.apache.cassandra.metrics:type=ThreadPools scope= type= name=`` ===================== ============== =========== 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..`` **JMX MBean** - ``org.apache.cassandra.metrics:type=ClientRequest scope={{RequestType}} name={{MetricName}}`` + ``org.apache.cassandra.metrics:type=ClientRequest scope= name=`` :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..`` **JMX MBean** - ``org.apache.cassandra.metrics:type=Cache scope={{CacheName}} name={{MetricName}}`` + ``org.apache.cassandra.metrics:type=Cache scope= name=`` ========================== ============== =========== 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.`` **JMX MBean** - ``org.apache.cassandra.metrics:type=CQL name={{MetricName}}`` + ``org.apache.cassandra.metrics:type=CQL name=`` ========================== ============== =========== 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..`` **JMX MBean** - ``org.apache.cassandra.metrics:type=DroppedMetrics scope={{Type}} name={{MetricName}}`` + ``org.apache.cassandra.metrics:type=DroppedMetrics scope= name=`` ========================== ============== =========== 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..`` **JMX MBean** - ``org.apache.cassandra.metrics:type=Streaming scope={{PeerIP}} name={{MetricName}}`` + ``org.apache.cassandra.metrics:type=Streaming scope= name=`` ========================== ============== =========== 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.`` **JMX MBean** - ``org.apache.cassandra.metrics:type=Compaction name={{MetricName}}`` + ``org.apache.cassandra.metrics:type=Compaction name=`` ========================== ======================================== =============================================== 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.`` **JMX MBean** - ``org.apache.cassandra.metrics:type=CommitLog name={{MetricName}}`` + ``org.apache.cassandra.metrics:type=CommitLog name=`` ========================== ============== =========== 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.`` **JMX MBean** - ``org.apache.cassandra.metrics:type=Storage name={{MetricName}}`` + ``org.apache.cassandra.metrics:type=Storage name=`` ========================== ============== =========== 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.`` **JMX MBean** - ``org.apache.cassandra.metrics:type=HintedHandOffManager name={{MetricName}}`` + ``org.apache.cassandra.metrics:type=HintedHandOffManager name=`` =========================== ============== =========== 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- Counter Number of hints on disk for this peer. +Hints_not_stored- 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..RowIndexEntry`` **JMX MBean** - ``org.apache.cassandra.metrics:type=Index scope=RowIndexEntry name={{MetricName}}`` + ``org.apache.cassandra.metrics:type=Index scope=RowIndexEntry name=`` =========================== ============== =========== 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.`` **JMX MBean** - ``org.apache.cassandra.metrics:type=BufferPool name={{MetricName}}`` + ``org.apache.cassandra.metrics:type=BufferPool name=`` =========================== ============== =========== 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.`` **JMX MBean** - ``org.apache.cassandra.metrics:type=Client name={{MetricName}}`` + ``org.apache.cassandra.metrics:type=Client name=`` =========================== ============== =========== Name Type Description