From 2bb4dabcf88e63c54f7c57e2e80ad2ca77a04b40 Mon Sep 17 00:00:00 2001 From: mspronesti Date: Sun, 24 Apr 2022 00:23:01 +0200 Subject: [PATCH] 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 | 3 + docs/_static/style.css | 138 ++++++++++++++++++++--- docs/_static/theme_override.css | 30 +++++ docs/conf.py | 5 +- docs/{readme.rst => getting_started.rst} | 0 docs/index.rst | 2 +- requirements-dev.txt | 2 +- 7 files changed, 163 insertions(+), 17 deletions(-) create mode 100644 docs/_static/theme_override.css rename docs/{readme.rst => getting_started.rst} (100%) diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index e21fbc4..1c7769a 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.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: | diff --git a/docs/_static/style.css b/docs/_static/style.css index a718330..6a04e13 100644 --- a/docs/_static/style.css +++ b/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 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; +} + diff --git a/docs/_static/theme_override.css b/docs/_static/theme_override.css new file mode 100644 index 0000000..49dab7b --- /dev/null +++ b/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 } diff --git a/docs/conf.py b/docs/conf.py index abd455e..44371f0 100644 --- a/docs/conf.py +++ b/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", diff --git a/docs/readme.rst b/docs/getting_started.rst similarity index 100% rename from docs/readme.rst rename to docs/getting_started.rst diff --git a/docs/index.rst b/docs/index.rst index 4592446..afab9c8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,7 +22,7 @@ Table of Contents :maxdepth: 1 :caption: Contents: - Getting Started + Getting Started Qlearnkit Module API Tutorials diff --git a/requirements-dev.txt b/requirements-dev.txt index 88ea1ff..25421b7 100644 --- a/requirements-dev.txt +++ b/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