Made a custom theme for sphinx documentation (#1847)

docs/Makefile

@@ -20,6 +20,9 @@ help:
 	python3 apidoc.py
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+quick:
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
 clean:
 	rm -fr doxygen-out
 	rm -fr source/api

docs/cutter_theme/layout.html

@@ -0,0 +1,45 @@
+{% extends 'basic/layout.html' %}
+{% block extrahead %}
+{% endblock %}
+
+{# https://www.sphinx-doc.org/en/master/templating.html #}
+
+{% block relbar2 %}
+{% endblock %}
+
+{% block header %}
+    {% if pagename == 'index' %}<div class=indexwrapper>{% endif %}
+{% endblock %}
+
+{% block sidebar1 %}
+{% endblock %}
+
+{% block sidebar2 %}
+ {%- if render_sidebar %}
+  <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+    <div class="sphinxsidebarwrapper">
+      {%- block sidebarlogo %}
+      {%- if logo %}
+        <p class="logo"><a href="https://cutter.re/">
+          <img class="logo" src="{{ pathto('_static/' + logo, 1) }}" alt="Logo"/>
+        </a></p>
+      {%- endif %}
+      {%- endblock %}
+      <a href="{{ pathto(master_doc) }}">{{ project }} documentation</a>
+      {%- 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 #}
+      {%- endif %}
+    </div>
+  </div>
+ {%- endif %}
+{% endblock %}
+
+{% block footer %}
+    {{ super() }}
+    {% if pagename == 'index' %}</div>{% endif %}
+{% endblock %}

docs/cutter_theme/static/cutter.css_t

@@ -0,0 +1,441 @@
+/*
+ * cutter.css_t
+ * based on flasky.css_t by Armin Ronacher
+ * ~~~~~~~~~~~~
+ *
+ */
+
+{% set page_width = '1300px' %}
+{% set sidebar_width = '220px' %}
+
+@import url('https://fonts.googleapis.com/css?family=Poppins&display=swap');
+@import url('https://fonts.googleapis.com/css?family=Inconsolata&display=swap');
+@import url('basic.css');
+
+/* -- page layout ---------------------------------------------------------- */
+
+body {
+    font-family: "Poppins", sans-serif;
+    font-size: 16px;
+    background-color: white;
+    color: #0d1b33;
+    margin: 0;
+    padding: 0;
+}
+
+div.document {
+    width: {{ page_width }};
+    margin: 30px auto 0 auto;
+}
+
+div.documentwrapper {
+    float: left;
+    width: 100%;
+}
+
+div.bodywrapper {
+    margin: 0 0 0 {{ sidebar_width }};
+}
+
+div.sphinxsidebar {
+    width: {{ sidebar_width }};
+}
+
+hr {
+    border: 1px solid #b1b4b6;
+}
+
+div.body {
+    background-color: #fff;
+    color: #3e4349;
+    padding: 0 30px 0 30px;
+}
+
+img.floatingflask {
+    padding: 0 0 10px 10px;
+    float: right;
+}
+
+div.footer {
+    width: {{ page_width }};
+    margin: 20px auto 30px auto;
+    font-size: 14px;
+    color: #888;
+    text-align: right;
+}
+
+div.footer a {
+    color: #888;
+}
+
+div.related {
+    display: none;
+}
+
+div.sphinxsidebar a {
+    color: #444;
+    text-decoration: none;
+    border-bottom: 1px solid #999;
+}
+
+div.sphinxsidebar a:hover {
+    color: #216ae6;
+    border-bottom: 1px solid #999;
+}
+
+div.sphinxsidebar {
+    font-size: 14px;
+    line-height: 1.5;
+}
+
+div.sphinxsidebarwrapper {
+    padding: 18px 10px;
+}
+
+div.sphinxsidebarwrapper p.logo {
+    padding: 0 0 20px 0;
+    margin: 0;
+    text-align: center;
+}
+
+div.sphinxsidebar h3,
+div.sphinxsidebar h4 {
+    font-family: Content-font, Roboto, sans-serif;
+    color: #444;
+    font-size: 24px;
+    font-weight: normal;
+    margin: 0 0 5px 0;
+    padding: 0;
+}
+
+div.sphinxsidebar h4 {
+    font-size: 20px;
+}
+
+div.sphinxsidebar h3 a {
+    color: #444;
+}
+
+div.sphinxsidebar p.logo a,
+div.sphinxsidebar h3 a,
+div.sphinxsidebar p.logo a:hover,
+div.sphinxsidebar h3 a:hover {
+    border: none;
+}
+
+div.sphinxsidebar p {
+    color: #555;
+    margin: 10px 0;
+}
+
+div.sphinxsidebar ul {
+    margin: 10px 0;
+    padding: 0;
+    color: #000;
+}
+
+div.sphinxsidebar input {
+    border: 1px solid #ccc;
+    font-family: Content-font, Roboto, sans-serif;
+    font-size: 1em;
+}
+
+/* -- body styles ---------------------------------------------------------- */
+
+a {
+    color: #004b6b;
+    text-decoration: underline;
+}
+
+a:hover {
+    color: #6d4100;
+    text-decoration: underline;
+}
+
+div.body h1,
+div.body h2,
+div.body h3,
+div.body h4,
+div.body h5,
+div.body h6 {
+    color: #041e49;
+    font-family: Content-font, Roboto, sans-serif;
+    font-weight: 400;
+    margin: 30px 0 10px 0;
+    padding: 0;
+}
+
+{% if theme_index_logo %}
+div.indexwrapper h1 {
+    text-indent: -999999px;
+    background: url({{ theme_index_logo }}) no-repeat center center;
+    height: {{ theme_index_logo_height }};
+}
+{% endif %}
+div.body h1 { margin-top: 0; padding-top: 0; font-size: 240%; }
+div.body h2 { font-size: 180%; }
+div.body h3 { font-size: 150%; }
+div.body h4 { font-size: 130%; }
+div.body h5 { font-size: 100%; }
+div.body h6 { font-size: 100%; }
+
+a.headerlink {
+    color: #216ae6;
+    padding: 0 4px;
+    text-decoration: none;
+}
+
+a.headerlink:hover {
+    color: #041e49;
+}
+
+div.body p, div.body dd, div.body li {
+    line-height: 1.4;
+}
+
+dt:target, .highlight {
+    background: #faf3e8;
+}
+
+div.note {
+    background-color: #eee;
+    border: 1px solid #ccc;
+}
+
+div.seealso {
+    background-color: #ffc;
+    border: 1px solid #ff6;
+}
+
+div.topic {
+    background-color: #eee;
+}
+
+img.screenshot {
+}
+
+img.screenshot {
+    -moz-box-shadow: 2px 2px 4px #eee;
+    -webkit-box-shadow: 2px 2px 4px #eee;
+    box-shadow: 2px 2px 4px #eee;
+}
+
+table.docutils {
+    border: 1px solid #888;
+    -moz-box-shadow: 2px 2px 4px #eee;
+    -webkit-box-shadow: 2px 2px 4px #eee;
+    box-shadow: 2px 2px 4px #eee;
+}
+
+table.docutils td, table.docutils th {
+    border: 1px solid #888;
+    padding: 0.25em 0.7em;
+}
+
+table.field-list, table.footnote {
+    border: none;
+    -moz-box-shadow: none;
+    -webkit-box-shadow: none;
+    box-shadow: none;
+}
+
+table.footnote {
+    margin: 15px 0;
+    width: 100%;
+    border: 1px solid #eee;
+    background: #fdfdfd;
+    font-size: 0.9em;
+}
+
+table.footnote + table.footnote {
+    margin-top: -15px;
+    border-top: none;
+}
+
+table.field-list th {
+    padding: 0 0.8em 0 0;
+}
+
+table.field-list td {
+    padding: 0;
+}
+
+table.footnote td.label {
+    width: 0;
+    padding: 0.3em 0 0.3em 0.5em;
+}
+
+table.footnote td {
+    padding: 0.3em 0.5em;
+}
+
+dl {
+    margin: 0;
+    padding: 0;
+}
+
+dl dd {
+    margin-left: 30px;
+}
+
+blockquote {
+    margin: 0 0 0 30px;
+    padding: 0;
+}
+
+ul, ol {
+    margin: 10px 0 10px 30px;
+    padding: 0;
+}
+
+pre {
+    background: #fafafa;
+    padding: 7px 30px;
+    margin: 15px -30px;
+    line-height: 1.3;
+    font-family: 'Inconsolata', monospace;
+}
+
+span.pre {
+    color: #e83e8c;
+    word-break: break-word;
+    font-family: SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,monospace;
+}
+
+dl pre, blockquote pre, li pre {
+    margin-left: -60px;
+    padding-left: 60px;
+}
+
+dl dl pre {
+    margin-left: -90px;
+    padding-left: 90px;
+}
+
+a.reference {
+    color: #216ae6;
+    text-decoration: none;
+}
+
+a.reference:hover {
+    color: #216ae6;
+    border-bottom: 1px solid;
+}
+
+a.footnote-reference {
+    color: #216ae6;
+    text-decoration: none;
+    font-size: 0.7em;
+    vertical-align: top;
+    border-bottom: 1px solid;
+}
+
+a.footnote-reference:hover {
+    color: #216ae6;
+    border-bottom: 1px solid;
+}
+
+/* Notes box */
+.admonition {
+    border-radius: 5px;
+}
+
+.admonition.note {
+    color: #0c5460;
+    background-color: #d1ecf1;
+    border-color: #bee5eb;
+}
+
+/* API Reference */
+
+.rst-content dl:not(.docutils) dt {
+}
+
+code.descname {
+    font-size: 14px;
+}
+
+.sig-paren {
+    font-size: 14px;
+}
+
+@media screen and (max-width: 875px) {
+    body {
+        margin: 0;
+        padding: 20px 30px;
+    }
+
+    div.documentwrapper {
+        float: none;
+        background: white;
+        margin: 0;
+    }
+
+    div.sphinxsidebar {
+        display: block;
+        float: none;
+        width: 102.5%;
+        margin: 50px -30px 0;
+        padding: 10px 30px;
+        background: #333;
+        color: white;
+    }
+
+    div.sphinxsidebarwrapper {
+        padding: 0;
+    }
+
+    div.sphinxsidebar h3, div.sphinxsidebar h4, div.sphinxsidebar p,
+    div.sphinxsidebar h3 a {
+        color: white;
+    }
+
+    div.sphinxsidebar a {
+        color: #aaa;
+    }
+
+    div.sphinxsidebar p.logo {
+        display: none;
+    }
+
+    div.document {
+        width: 100%;
+        margin: 0;
+    }
+
+    div.related {
+        display: block;
+        margin: 0;
+        padding: 10px 0 20px 0;
+    }
+
+    div.related ul,
+    div.related ul li {
+        margin: 0;
+        padding: 0;
+    }
+
+    div.bodywrapper {
+        margin: 0;
+    }
+
+    div.body {
+        min-height: 0;
+        padding: 0;
+    }
+
+    .rtd_doc_footer {
+        display: none;
+    }
+
+    div.footer {
+        width: auto;
+        margin: 0 -30px -20px;
+        padding: 10px 30px 20px;
+        background: #333;
+    }
+
+    ul {
+        margin-left: 0;
+    }
+}

docs/cutter_theme/theme.conf

@@ -0,0 +1,11 @@
+[theme]
+inherit = basic
+stylesheet = cutter.css
+pygments_style = flasky
+
+[options]
+index_logo =
+index_logo_height = 120px
+touch_icon =
+github_fork =
+github_ribbon_color = darkblue_121621

docs/source/building.rst

@@ -1,7 +1,11 @@
 Building
 ========
 
-Below you will find the instructions for building Cutter.
+.. note::
+
+ If you just want to use the latest Release version of Cutter, please note
+ that we provide pre-compiled binaries for Windows, Linux and macOS on
+ our `release page. <https://github.com/radareorg/cutter/releases/latest>`_
 
 
 Building on Linux
@@ -34,7 +38,7 @@ Building steps
 The official way to build Cutter on Linux is by using CMake.
 First clone the repository with its dependencies:
 
-::
+.. code-block:: sh
 
    git clone --recurse-submodules https://github.com/radareorg/cutter
 

docs/source/conf.py

@@ -24,9 +24,9 @@ copyright = '2019, The Cutter Developers'
 author = 'The Cutter Developers'
 
 # The short X.Y version
-version = ''
+version = '1.9'
 # The full version, including alpha/beta/rc tags
-release = ''
+release = '1.9.0'
 
 
 # -- General configuration ---------------------------------------------------
@@ -38,16 +38,18 @@ release = ''
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [ "breathe" ]
+extensions = [
+    'breathe',
+]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['sphinx_templates']
+templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-# source_suffix = ['.rst', '.md']
+# source_suffix = '.rst'
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
 
 # The master toctree document.
 master_doc = 'index'
@@ -62,15 +64,15 @@ language = None
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = ['_build']
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = None
+pygments_style = 'rainbow_dash'
 
 # -- Options for Breathe -----------------------------------------------------
 
-breathe_projects = { "cutter": "../doxygen-out/xml" }
+breathe_projects = { 'cutter': '../doxygen-out/xml' }
-breathe_default_project = "cutter"
+breathe_default_project = 'cutter'
 breathe_default_members = ('members', 'undoc-members')
 
 # -- Options for HTML output -------------------------------------------------
@@ -78,7 +80,9 @@ breathe_default_members = ('members', 'undoc-members')
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'cutter_theme'
+html_theme_path = ['..']
+html_logo = '../../src/img/cutter.ico'
 
 # 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
@@ -89,23 +93,25 @@ html_theme = 'sphinx_rtd_theme'
 # 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 = ['sphinx_static']
+# html_static_path = ['static']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
 #
 # The default sidebars (for documents that don't match any pattern) are
 # defined by theme itself.  Builtin themes are using these templates by
-# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# Default: html_sidebars = {
-# 'searchbox.html']``.
+#   '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
-#
+#   'using/windows': ['windowssidebar.html', 'searchbox.html'],
-# html_sidebars = {}
+# }
-
+html_sidebars = {
+   '**': ['globaltoc.html'],
+}
 
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'Cutterdoc'
+htmlhelp_basename = 'CutterDoc'
 
 
 # -- Options for LaTeX output ------------------------------------------------

docs/source/index.rst

@@ -1,5 +1,5 @@
-Cutter Documentation
+Cutter
-====================
+======
 
 Cutter is a Qt and C++ GUI for radare2. Its goal is making an advanced,
 customizable and FOSS reverse-engineering platform while keeping the
@@ -15,6 +15,7 @@ Get Cutter
 Cutter is available for all platforms (Linux, OS X, Windows). You can
 download the latest release
 `here <https://github.com/radareorg/cutter/releases>`__.
+
 - OSX: Download the latest ``.dmg`` file.
 - Windows: Download the latest archive.
 - Linux: use the AppImage file. Then just make it executable and run it: ``chmod +x Cutter-v1.9.0-x86_64.AppImage``
@@ -42,7 +43,6 @@ If you want to contribute to Cutter, take a look
 `here <https://github.com/radareorg/cutter/blob/master/CONTRIBUTING.md>`__
 to know what you can do to help the project!
 
-
 .. toctree::
    :maxdepth: 2
    :caption: Contents: