docs: chore documentation pre-release

* change theme : pydata to read-the-docs
* add theme overrides vie css
* rename readme.rst to getting_started.rst
* add missing torch and pennylane pip install to deploy docs action

.github/workflows/deploy-docs.yml

@@ -5,13 +5,16 @@ on:
 
 jobs:
   docs:
+
     runs-on: ubuntu-latest
+
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v2
       - name: Install dependencies
         run: |
           sudo apt install pandoc
+          pip install torch pennylane
           pip install -r requirements-dev.txt
       - name: Sphinx build
         run: |

docs/_static/style.css

@@ -1,17 +1,5 @@
-/* To have blue background of width of the block (instead of width of content) */
-dl.class > dt:first-of-type {
-    display: block !important;
-}
-
-.xref.py.py-class,
-.xref.py.py-data,
-.xref.py.py-obj
-{
-    background-color: #f0f0f0;
-}
-
-
 /* To customize thumbnails in tutorials gallery */
+
 .sphx-glr-thumbcontainer {
     min-height: 320px !important;
     margin: 20px !important;
@@ -26,3 +14,127 @@ dl.class > dt:first-of-type {
 .sphx-glr-thumbcontainer a.internal {
     padding: 170px 90px 0 !important;
 }
+
+
+/* Custom classes */
+
+.small { font-size:40% }
+.smaller, .pr { font-size:70% }
+
+
+/* Custom classes with bootstrap buttons */
+
+.tutorial,
+.tutorial:visited,
+.tutorial:hover
+{
+    /* text-decoration: underline; */
+    font-weight: bold;
+    padding: 2px 5px;
+    white-space: nowrap;
+    max-width: 100%;
+    background: #EF3270;  /* color from the tail of the scampy */
+    border: solid 1px #EF3270;
+    border-radius: .25rem;
+    font-size: 75%;
+    /* font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace; */
+    /*color: #404040;*/
+    overflow-x: auto;
+    box-sizing: border-box;
+}
+
+
+/* Formatting of RTD markup: rubrics and sidebars and admonitions */
+
+/* rubric */
+.rst-content p.rubric {
+    margin-bottom: 6px;
+    font-weight: normal;
+}
+.rst-content p.rubric::after { content: ":" }
+
+/* sidebar */
+.rst-content .sidebar {
+    /* margin: 0px 0px 0px 12px; */
+    padding-bottom: 0px;
+}
+.rst-content .sidebar p {
+    margin-bottom: 12px;
+}
+.rst-content .sidebar p,
+.rst-content .sidebar ul,
+.rst-content .sidebar dl {
+    font-size: 13px;
+}
+
+/* less space after bullet lists in admonitions like warnings and notes */
+.rst-content .section .admonition ul {
+    margin-bottom: 6px;
+}
+
+
+/* Code: literals and links */
+
+.rst-content tt.literal,
+.rst-content code.literal {
+    color: #404040;
+}
+/* slim font weight for non-link code */
+.rst-content tt:not(.xref),
+.rst-content code:not(.xref),
+.rst-content *:not(a) > tt.xref,
+.rst-content *:not(a) > code.xref,
+.rst-content dl:not(.docutils) code
+{
+    font-weight: normal;
+}
+.rst-content a > tt.xref,
+.rst-content a > code.xref,
+.rst-content dl:not(.docutils) a > tt.xref,
+.rst-content dl:not(.docutils) a > code.xref
+{
+    font-weight: bold;  /* underline looks clumsy, in particular with buttons and
+                           other hyperlinks, which don't come with underlines */
+}
+
+
+/* Just one box for annotation code for a less noisy look */
+
+.rst-content .annotation {
+    padding: 2px 5px;
+    background-color: white;
+    border: 1px solid #e1e4e5;
+}
+.rst-content .annotation tt,
+.rst-content .annotation code {
+    padding: 0 0;
+    background-color: transparent;
+    border: 0 solid transparent;
+}
+
+
+/* Parameter lists */
+
+/* Mimick rubric style used for other headings */
+/* TODO: once scanpydoc adds classes, also change return types like this */
+.rst-content dl:not(.docutils) dl > dt {
+    font-weight: bold;
+    background: none transparent;
+    border-left: none;
+    margin: 0 0 12px;
+    padding: 3px 0 0;
+    font-size: 111.11%;
+}
+/* Parameters contain <strong> parts and don’t need bold font */
+.rst-content dl.field-list dl > dt { font-weight: unset }
+/* Add colon between return tuple element name and type */
+.rst-content dl:not(.docutils) dl > dt .classifier::before { content: ' : ' }
+
+/* Function headers */
+
+.rst-content dl:not(.docutils) dt {
+    background: #edf0f2;
+    color: #404040;
+    border-top: solid 3px #343131;
+}
+

docs/_static/theme_override.css

@@ -0,0 +1,30 @@
+/* border in tutorial boxes */
+.sphx-glr-thumbcontainer {
+    border-color: #E8E3E3 !important;
+}
+
+
+/* Blue background of width of the block (instead of width of content) */
+dl.class > dt:first-of-type {
+    display: block !important;
+}
+
+.xref.py.py-class,
+.xref.py.py-data,
+.xref.py.py-obj
+{
+    background-color: #f0f0f0;
+}
+
+/* ReadTheDocs top left panel color */
+
+.wy-nav-top { background-color: #f07e44 }
+
+/* extend page width*/
+.wy-nav-content {
+    max-width: 1200px;
+}
+
+/* left search nav*/
+.wy-side-nav-search { background-color: transparent }
+.wy-side-nav-search input[type="text"] { border-width: 0 }

docs/conf.py

@@ -40,6 +40,7 @@
     "sphinx.ext.viewcode",
     "sphinx_autodoc_typehints",
     "jupyter_sphinx",
+    "sphinx_rtd_theme",
     "sphinx_gallery.load_style",
 ]
 
@@ -60,7 +61,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 
-html_theme = "pydata_sphinx_theme"
+html_theme = "sphinx_rtd_theme"
 
 # The suffix of source filenames.
 source_suffix = ".rst"
@@ -69,7 +70,7 @@
 # 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_css_files = ["style.css"]
+html_css_files = ["style.css", "theme_override.css"]
 
 nbsphinx_thumbnails = {
     "tutorials/qlstm_tagger": "_static/thumbnail/qlstm.png",

docs/index.rst

@@ -22,7 +22,7 @@ Table of Contents
    :maxdepth: 1
    :caption: Contents:
 
-   Getting Started <readme>
+   Getting Started <getting_started>
    Qlearnkit Module API <apidoc/qlearnkit>
    Tutorials <tutorials/index>
 

requirements-dev.txt

@@ -18,7 +18,7 @@ sphinxcontrib-serializinghtml==1.1.5
 sphinx-autodoc-typehints==1.14.0
 sphinx-gallery
 pandoc>=1.1.0
-pydata-sphinx-theme>=0.4.1
+sphinx-rtd-theme
 nbsphinx
 nbsphinx-link
 matplotlib>=3.3