Fix docs, add theme html files

README.md

@@ -1,4 +1,4 @@
-# cyclops-query
+cyclops-query
 --------------------------------------------------------------------------------
 
 [![PyPI](https://img.shields.io/pypi/v/cycquery)](https://pypi.org/project/cycquery)

docs/source/intro.rst

@@ -1,5 +1,5 @@
-# cyclops-query
-===============
+cyclops-query
+=============
 
 |PyPI| |code checks| |integration tests| |docs| |codecov| |license|
 

docs/source/theme/breadcrumbs.html

@@ -0,0 +1,41 @@
+{% extends "sphinx_rtd_theme/breadcrumbs.html" %}
+
+{% block breadcrumbs %}
+  {# Separators between <li>s are added by CSS. #}
+
+  {#
+    Breadcrumbs always start with home icon pointing to the main Nextstrain doc
+    project.
+
+    If the current project is the main project, then we don't hardcode the URL
+    so the currently viewed version/language is preserved (although we don't
+    use these features currently).
+  #}
+  {% if theme_subproject %}
+    <li><a href="https://vectorinstitute.github.io/cyclops/">Home</a></li>
+    <li><a href="{{ pathto(master_doc) }}">{{ project }}</a></li>
+  {% else %}
+    <li><a href="{{ pathto(master_doc) }}">Home</a></li>
+  {% endif %}
+
+  {#
+    The parents of the current page, according to the project toctree, without
+    the root doc (master_doc).
+  #}
+  {% for doc in parents %}
+    <li><a href="{{ doc.link|e }}">{{ doc.title }}</a></li>
+  {% endfor %}
+
+  {#
+    Don't include the current page's title (like the template we're extending
+    does) because the page title is immediately below these breadcrumbs anyway.
+
+    This also follows common UX recommendations for breadcrumbs, e.g. the UK's
+    Government Digital Service (gov.uk) breadcrumbs component guidelines¹ says:
+
+        The breadcrumb should start with your ‘home’ page and end with the
+        parent section of the current page.
+
+    ¹ https://design-system.service.gov.uk/components/breadcrumbs/
+  #}
+{% endblock %}

docs/source/theme/footer.html

@@ -0,0 +1,63 @@
+{% extends "sphinx_rtd_theme/footer.html" %}
+
+{#
+  The design of the rtd-theme footer template includes content which is
+  not inside a block (and thus not trivial to overwrite). By setting
+  the following variabels we essentially hide footer content which we want
+  to include ourselves. P.S. These variables are only used in the footer.
+#}
+{% set show_sphinx = false %}
+{% set show_copyright = false %}
+
+{#
+  Footer design largely replicates https://github.com/nextstrain/nextstrain.org/raw/0c3222d/static-site/src/components/Footer/index.jsx
+#}
+
+{#
+  The following could probably be written in a much nicer, less verbose style.
+  This is/was my first time using Jinja, so i'm falling back onto basic HTML.
+  If you can improve this, please do & show me the way!       james oct 2020
+#}
+{% block extrafooter %}
+
+  <div class="footer-small-text">
+    All <a href="https://github.com/VectorInstitute/cyclops">source code for cyclops</a> is freely available under the terms of an <a href="https://opensource.org/licenses/Apache-2.0">Apache-2.0</a> license.
+  </div>
+
+  <div class="footer-small-text">
+      This work is made possible due to the data obtained from the <a href="https://www.geminimedicine.ca/">GEMINI study</a>.
+  </div>
+
+  <hr/>
+
+  <div class="logo">
+    <a class="logo" href="https://vectorinstitute.ai/">
+      <span class="logo"></span>
+      <img alt="Logo of the Vector Institute" style="width:90px; max-width:90px;" src="{{ pathto('_static/logos/vector_logo.png', 1) }}" />
+    </a>
+    <a class="logo" href="https://www.geminimedicine.ca/">
+      <span class="logo"></span>
+      <img alt="Logo of GEMINI" style="width:90px; max-width:90px;" src="{{ pathto('_static/logos/gemini_logo.png', 1) }}" />
+    </a>
+  </div>
+
+  <div class="copyright">
+    &copy; {% trans %}Copyright{% endtrans %} {{ copyright }}
+  </div>
+
+  <div class="copyright">
+    {%- if build_id and build_url %}
+      Build <a href="{{ build_url }}">{{ build_id }}</a>.
+    {%- elif commit %}
+      Revision <code>{{ commit }}</code>.
+    {%- endif %}
+    {%- if last_updated %}
+      Last updated on {{ last_updated }}.
+    {%- endif %}
+    </p>
+    Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using customised version of
+    <a href="https://github.com/readthedocs/sphinx_rtd_theme">base theme</a> provided by
+    <a href="https://readthedocs.org">Read the Docs</a>.
+  </div>
+
+{% endblock %}

docs/source/theme/layout.html

@@ -0,0 +1,117 @@
+{#
+  Use our theme's favicon by default.  We do it here layout.html since the
+  "html_favicon" configuration option unfortunately can't be set by the theme
+  directly.  The "favicon" variable is used by Sphinx versions < 4;
+  "favicon_url" by newer versions.
+#}
+{% if not favicon %}
+{%   set favicon     = 'favicon.ico' %}
+{%   set favicon_url = pathto('_static/' + favicon, 1) %}
+{% endif %}
+
+{% extends "sphinx_rtd_theme/layout.html" %}
+{#
+  Most of this block is copied from sphinx_rtd_theme version 0.5.0-1-gaa71fd6.
+
+  Tweaks were necessary for our theme to provide a default logo, since Sphinx's
+  html_logo configuration option (template variable "logo" below) can't be set
+  by the theme *and also* can't refer to a theme-provided file when set by the
+  doc project's conf.py.
+
+  We also adjust the rendering of the project name to remove the home icon.
+#}
+{% block sidebartitle %}
+
+{% set logo = logo if logo else 'cyclops_logo-dark.png' if theme_logo else '' %}
+
+{% if logo %}
+  <a href="{{ theme_logo_link }}">
+    <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="{{ _('Logo') }}"/>
+  </a>
+{% endif %}
+
+{% if theme_subproject %}
+  <div class="subproject">
+    <a href="{{ pathto(master_doc) }}" class="project-name" alt="{{ _("Documentation Home") }}">
+      {{ project }}
+    </a>
+
+    {#
+      NOTE the version only works on RTD (not locally) as the variables `nav_version` and
+      `current_version` don't seem to be set on a local build.
+    #}
+    {%- set nav_version = version %}
+    {% if READTHEDOCS and current_version %}
+      {%- set nav_version = current_version %}
+    {% endif %}
+    {% if nav_version %}
+      <div class="version">
+        {% if nav_version == "stable" %}
+          stable version
+          {% if version and version != "stable" %}
+            <small>({{ version }})</small>
+          {% endif %}
+        {% elif nav_version == "latest" %}
+          development version
+          {% if commit %}
+            <small>(<tt>{{ commit }}</tt>)</small>
+          {% endif %}
+        {% else %}
+          version {{ nav_version }}
+        {% endif %}
+      </div>
+    {% endif %}
+
+  </div>
+
+{% endif %}
+
+{% include "searchbox.html" %}
+
+{% endblock %}
+
+
+{% block extrabody %}
+  <!--
+    Lie about what theme we really are when some RTD-injected JS fetches the
+    full versions panel from the RTD API.  RTD's JS replaces the stub versions
+    panel in the Sphinx-generated HTML with the full versions panel it fetches
+    from the RTD API.  If the API thinks we're not sphinx_rtd_theme, it will
+    serve us the wrong HTML and the panel will float as a "badge" when it
+    shouldn't.  As a customized version of sphinx_rtd_theme, we really do want
+    the same HTML it gets.  See also the diagnoses in
+    <https://github.com/nextstrain/docs.nextstrain.org/issues/76>.
+
+    This bit of JS finds the data RTD injects into the page and modifies it
+    before the code that RTD injects runs and looks at the data.  RTD's
+    <script>s (in <head>) run before this JS, but they wait until the DOM is
+    ready to actually do any work.  This gives us a chance to modify the data
+    during DOM load before the RTD code actually uses it.
+
+      -trs, 27 Jan 2022
+  -->
+  <script>
+    (() => {
+      try {
+        console.log("Lying about the theme to RTD's JS so the versions panel works properly. 🙈");
+
+        /* Update global variable, which is used in the request to get the RTD
+         * "footer" that includes the versions panel.
+         */
+        if (window.READTHEDOCS_DATA)
+          window.READTHEDOCS_DATA.theme = "sphinx_rtd_theme";
+
+        /* Update stored JSON in case anything else deserializes it later.
+         * Comments in the RTD-injected HTML source claim the global variable
+         * above is deprecated.
+         */
+        var script = document.querySelector("#READTHEDOCS_DATA");
+        if (script)
+          script.innerHTML = JSON.stringify({ ...JSON.parse(script.innerHTML), theme: "sphinx_rtd_theme" });
+      }
+      catch (err) {
+        console.log("Lying about the theme to RTD's JS failed… oh well. 🤷", err);
+      }
+    })();
+  </script>
+{% endblock %}

docs/source/tutorials.rst

@@ -1,6 +1,16 @@
 Tutorials
 =========
 
+The cyclops-query tool allows you to query EHR databases. It is a Python API that
+that communicates with postgresql databases. It is a wrapper around the
+SQLAlchemy ORM and uses SQLAlchemy query objects and functions to build
+queries.
+
+
 .. toctree::
 
-   tutorials_query
+    tutorials/mimiciii.ipynb
+    tutorials/mimiciv.ipynb
+    tutorials/eicu.ipynb
+    tutorials/omop.ipynb
+    tutorials/gemini.ipynb