Merge pull request #10 from OpenSMFS/docs_theme

Docs: Implement new theme for sphinx documentation
OpenSMFS · Nov 23, 2017 · f2c0ef2 · f2c0ef2
2 parents 03e68ee + ce18f5f
commit f2c0ef2
Show file tree

Hide file tree

Showing 15 changed files with 205 additions and 90 deletions.
diff --git a/docs/environment.yml b/docs/environment.yml
@@ -0,0 +1,19 @@
+name: fretbursts-docs
+
+channels:
+- conda-forge
+- default
+
+dependencies:
+- python=3.6
+- setuptools
+- matplotlib
+- cython
+- pytables
+- lmfit
+- mock
+- pandas
+- phconvert
+- sphinx_bootstrap_theme
+- pip:
+  - seaborn
diff --git a/docs/environment_py35.yml b/docs/environment_py35.yml
diff --git a/docs/rtd_requirements.txt b/docs/rtd_requirements.txt
@@ -0,0 +1 @@
+seaborn
diff --git a/docs/source/_static/favicon.png b/docs/source/_static/favicon.png
diff --git a/docs/source/_static/logo.png b/docs/source/_static/logo.png
diff --git a/docs/source/_static/style.css b/docs/source/_static/style.css
@@ -0,0 +1,40 @@
+h1 { font-size: 40px !important; }
+h2 { font-size: 32px !important; }
+h3 { font-size: 24px !important; }
+h4 { font-size: 18px !important; }
+h5 { font-size: 14px !important; }
+h6 { font-size: 10px !important; }
+
+footer a{
+
+    color: #4c72b0 !important;
+}
+a.reference {
+    color: #4c72b0 !important;
+}
+
+blockquote p {
+    font-size: 14px !important;
+}
+
+blockquote {
+    margin: 0 0 4px !important;
+}
+
+code {
+    color: #49759c !important;
+    background-color: #ffffff !important;
+}
+
+.alert-info {
+    background-color: #adb8cb !important;
+    border-color: #adb8cb !important;
+    color: #2c3e50 !important;
+}
+
+.function dt {
+    padding-top: 150px;
+    margin-top: -150px;
+    -webkit-background-clip: content-box;
+    background-clip: content-box;
+}
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -54,18 +54,52 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('../..'))
 import fretbursts
-version = fretbursts._version.get_versions()['version']
-if on_rtd:
-    # RTD modifies conf.py so the git repo becomes dirty
-    # We strip the '-dirty' that would generate a wrong verion string
-    version = version.replace('.dirty', '')
+version = fretbursts._version.get_versions()['version'][:13]
 release = version
 
+import sphinx_bootstrap_theme
+html_theme = 'bootstrap'
+html_theme_options = {
+    'source_link_position': "footer",
+    'bootswatch_theme': "paper",
+    'navbar_sidebarrel': False,
+    'bootstrap_version': "3",
+    'navbar_links': [
+                     #("Gallery", "examples/index"),
+                     ("Tutorial", "tutorial"),
+                     ("API", "api"),
+                     ],
+    }
+
+# Add any paths that contain custom themes here, relative to this directory.
+html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+html_favicon = "_static/favicon.png"
+
+# 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']
+
 
-if not on_rtd:
-    import sphinx_rtd_theme
-    html_theme = 'sphinx_rtd_theme'
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+# if not on_rtd:
+#     import sphinx_rtd_theme
+#     html_theme = 'sphinx_rtd_theme'
+#     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
     #html_theme_path = ["_themes", ]
 
 
@@ -178,7 +212,7 @@
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+html_logo = '_static/logo.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -188,7 +222,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', 'images']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -317,3 +351,10 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+
+# Add the 'copybutton' javascript, to hide/show the prompt in code
+# examples, originally taken from scikit-learn's doc/conf.py
+def setup(app):
+    #app.add_javascript('copybutton.js')
+    app.add_stylesheet('style.css')
diff --git a/docs/source/images/2cde_joint.png b/docs/source/images/2cde_joint.png
diff --git a/docs/source/images/BVA_joint.png b/docs/source/images/BVA_joint.png
diff --git a/docs/source/images/alex_jointplot_fit.png b/docs/source/images/alex_jointplot_fit.png
diff --git a/docs/source/images/fret_hist_fit.png b/docs/source/images/fret_hist_fit.png
diff --git a/docs/source/images/hist_bg_fit.png b/docs/source/images/hist_bg_fit.png
diff --git a/docs/source/images/timetrace_bursts.png b/docs/source/images/timetrace_bursts.png
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -3,46 +3,107 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to FRETBursts's documentation!
-======================================
 
-:Author: Antonino Ingargiola
-:Contact: tritemio@gmail.com
-:Version: |version| (:doc:`release notes <releasenotes>`)
 
-`FRETBursts <http://opensmfs.github.io/FRETBursts/>`__ is an open-source (GPLv2) python package for burst analysis of
-freely-diffusing single-molecule FRET data for single and multi-spot experiments.
+Single-molecule FRET burst analysis
+==========================================
 
-See :ref:`getting-started` for installation instructions.
-The development version can be found on the `GitHub repository <https://github.com/OpenSMFS/FRETBursts>`_.
-For information on new versions see :doc:`release notes <releasenotes>`.
 
-This documentation contains installation instructions and the
-reference API documentation.
+.. raw:: html
 
-Other FRETBursts-related resources include:
 
-- `FRETBursts Homepage <http://opensmfs.github.io/FRETBursts>`__: general overview of FRETBursts features and philosophy.
-- `FRETBursts Tutorials <https://github.com/OpenSMFS/FRETBursts_notebooks#fretbursts-notebooks>`__ a list of
-  Jupyter Notebooks that can be either viewed online or downloaded and executed locally.
-- `bioRxiv paper <http://dx.doi.org/10.1101/039198>`__ detailed description of burst analysis and FRETBursts usage.
-- `Blog post <http://tritemio.github.io/smbits/2016/02/19/fretbursts/>`__ announcing the bioRxiv paper.
+    <div style="clear: both"></div>
+    <div class="container-fluid hidden-xs">
+      <div class="row align-items-center">
 
+        <a href="http://nbviewer.jupyter.org/github/OpenSMFS/FRETBursts_notebooks/blob/master/notebooks/Example%20-%20Selecting%20FRET%20populations.ipynb">
+          <div class="col-sm-2 thumbnail">
+            <img src="_static/alex_jointplot_fit.png">
+          </div>
+        </a>
 
-Table of Contents
------------------
+        <a href="http://nbviewer.jupyter.org/github/OpenSMFS/FRETBursts_notebooks/blob/master/notebooks/Example%20-%20Background%20estimation.ipynb">
+          <div class="col-sm-2 thumbnail">
+            <img src="_static/hist_bg_fit.png">
+          </div>
+        </a>
 
-.. toctree::
-    :maxdepth: 1
+        <a href="http://nbviewer.jupyter.org/github/OpenSMFS/FRETBursts_notebooks/blob/master/notebooks/Example%20-%20Plotting%20timetraces%20with%20bursts.ipynb">
+          <div class="col-sm-2 thumbnail">
+            <img src="_static/timetrace_bursts.png">
+          </div>
+        </a>
 
-    getting_started
-    reference_manual
-    releasenotes
-    cython
+        <a href="http://nbviewer.jupyter.org/github/OpenSMFS/FRETBursts_notebooks/blob/master/notebooks/Example%20-%20Burst%20Variance%20Analysis.ipynb">
+          <div class="col-sm-2 thumbnail">
+            <img src="_static/BVA_joint.png">
+          </div>
+        </a>
 
-Indices and tables
-==================
+        <a href="http://nbviewer.jupyter.org/github/OpenSMFS/FRETBursts_notebooks/blob/master/notebooks/Example%20-%202CDE%20Method.ipynb">
+          <div class="col-sm-2 thumbnail">
+            <img src="_static/2cde_joint.png">
+          </div>
+        </a>
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+        <a href="http://nbviewer.jupyter.org/github/OpenSMFS/FRETBursts_notebooks/blob/master/notebooks/Example%20-%20FRET%20histogram%20fitting.ipynb">
+          <div class="col-sm-2 thumbnail">
+            <img src="_static/fret_hist_fit.png">
+          </div>
+        </a>
+
+      </div>
+    </div>
+    <br>
+
+
+
+    <div class="container-fluid">
+    <div class="row">
+    <div class="col-md-6">
+    <br>
+
+
+**FRETBursts** is an open-source
+python package for burst analysis of freely-diffusing
+`single-molecule FRET <https://en.wikipedia.org/wiki/Single-molecule_FRET>`__
+data for single and multi-spot experiments. FRETBursts supports both
+single-laser and dual-laser alternated excitation
+(`ALEX <https://doi.org/10.1073/pnas.0401690101>`__ and
+`PAX <https://doi.org/10.1007/s00249-007-0133-7>`__)
+as well as
+`ns-ALEX <https://doi.org/10.1073/pnas.0508584102>`__ (or
+`PIE <https://doi.org/10.1529/biophysj.105.064766>`__).
+
+We provide well-tested implementations of state-of-the-art
+algorithms for confocal smFRET analysis.
+We focus on computational reproducibility,
+by using `Jupyter notebook <http://jupyter.org/>`__ based interfaces.
+
+Please send questions or report issue on `GitHub <https://github.com/OpenSMFS/FRETBursts/issues>`__.
+
+.. raw:: html
+
+   </div>
+   <div class="col-md-3">
+   <h2>Documentation</h2>
+
+* `Introducing FRETBursts <http://tritemio.github.io/smbits/2016/02/19/fretbursts>`__
+* :doc:`Installation <getting_started>`
+* :doc:`What's new? <releasenotes>`
+* `μs-ALEX Tutorial <http://nbviewer.jupyter.org/github/OpenSMFS/FRETBursts_notebooks/blob/master/notebooks/FRETBursts%20-%20us-ALEX%20smFRET%20burst%20analysis.ipynb>`__
+* `List of Jupyter Notebooks <https://github.com/OpenSMFS/FRETBursts_notebooks#fretbursts-notebooks>`__
+* :doc:`Reference manual <reference_manual>`
+
+.. raw:: html
+
+   </div>
+   <div class="col-md-3">
+   <h2>Features</h2>
+
+* `FRETBursts Paper <http://dx.doi.org/10.1101/039198>`__
+* :doc:`Burst Search Algorithm <burstsearch>`
+* `BVA <http://nbviewer.jupyter.org/github/OpenSMFS/FRETBursts_notebooks/blob/master/notebooks/Example%20-%20Burst%20Variance%20Analysis.ipynb>`__
+* `2CDE <http://nbviewer.jupyter.org/github/OpenSMFS/FRETBursts_notebooks/blob/master/notebooks/Example%20-%202CDE%20Method.ipynb>`__
+* `Exporting burst data <http://nbviewer.jupyter.org/github/OpenSMFS/FRETBursts_notebooks/blob/master/notebooks/Example%20-%20Exporting%20Burst%20Data%20Including%20Timestamps.ipynb>`__
+* `Report an issue <https://github.com/opensmfs/FRETBursts/issues>`__
diff --git a/readthedocs.yml b/readthedocs.yml
@@ -1,5 +1,5 @@
 conda:
-    file: docs/environment_py35.yml
+    file: docs/environment.yml
 
 python:
    version: 3.5