From e198047b848496c6de0dcf615292a1b13c47492f Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 27 Oct 2022 17:25:02 +0200 Subject: [PATCH 1/9] Update to latest Sphinx, ablog and fail on warnings. Fix some broken intersphinx. Apply styles for ablog that aligns headers with post ul list. --- .readthedocs.yml | 1 + _themes/rtd-blog/static/local.css | 14 +++++++++++--- conf.py | 4 +--- embed-api-v3.rst | 4 ++-- requirements.txt | 10 +++++----- 5 files changed, 20 insertions(+), 13 deletions(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 309d307e..d5fa74ff 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -3,6 +3,7 @@ version: 2 sphinx: builder: dirhtml configuration: conf.py + fail_on_warning: true python: version: 3.7 diff --git a/_themes/rtd-blog/static/local.css b/_themes/rtd-blog/static/local.css index 223f743e..dcb11ac5 100644 --- a/_themes/rtd-blog/static/local.css +++ b/_themes/rtd-blog/static/local.css @@ -1,3 +1,8 @@ +h1, h2, h3, h4, h5, h6 +{ + margin: 1em 0; +} + div.section h1 { font-size: 1.3em; } @@ -16,7 +21,7 @@ div.section h4, div.section h5, div.section h6 { div.section ul { list-style: inside; - margin: 1em; + margin: 1em 0; } div.section p { @@ -96,15 +101,18 @@ table.footnote td.label { padding: .65em; } +.postlist { + margin: 1em 0; +} + .postlist li { list-style: none; } -.postlist p.first { +.postlist p.first, .postlist .ablog-post-title { font-size: 24px; } - img.align-center { display: block; margin: 0 auto; diff --git a/conf.py b/conf.py index 5cf87e74..45f43fe1 100644 --- a/conf.py +++ b/conf.py @@ -79,8 +79,6 @@ )) templates_path.append(ablog.get_html_templates_path()) -html4_writer = True - if os.environ.get('READTHEDOCS', None) == 'True': skip_pickling = True @@ -96,7 +94,7 @@ # General information about the project. project = u'Read the Docs Blog' -copyright = u'2021, Read the Docs, Inc' +copyright = u'Read the Docs, Inc' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the diff --git a/embed-api-v3.rst b/embed-api-v3.rst index d4b50c79..96bbdf5f 100644 --- a/embed-api-v3.rst +++ b/embed-api-v3.rst @@ -65,7 +65,7 @@ and with it, version 1.0 of sphinx-hoverxref**. Among other things, the new versions allow you to -:ref:`embed content from pages hosted outside Read the Docs `. +:ref:`embed content from pages hosted outside Read the Docs `. For security reasons, we have an allowlist of such external domains that currently includes Python, NumPy, SciPy, SymPy, and we would like to @@ -84,7 +84,7 @@ Embedding content with sphinx-hoverxref --------------------------------------- To use sphinx-hoverxref in your Read the Docs project, -:doc:`declare it as part of your dependencies `: +:doc:`declare it as part of your dependencies `: .. code-block:: :caption: requirements.txt diff --git a/requirements.txt b/requirements.txt index 61a57a21..721ae1a3 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,11 +1,11 @@ -Sphinx==2.4.4 +Sphinx==5.3.0 sphinxext-opengraph==0.4.2 docutils<0.18 -jinja2<3.1.0 +# jinja2<3.1.0 # Used to rewrite the Atom feed to use absolute links -lxml==4.6.5 +lxml==4.9.1 -ablog==0.9.5 +ablog==0.10.26 # This dependencie from ablog needs to be pinned -werkzeug==0.16.1 +# werkzeug==0.16.1 From 5fd9a468757e16a6369cce63510e8efe128a75a7 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 8 Nov 2022 17:14:47 +0100 Subject: [PATCH 2/9] Updates to CSS, reflecting more docutils DOM changes --- _themes/rtd-blog/static/local.css | 29 +++++++++++++++++------------ _themes/rtd-blog/static/main.css | 2 +- 2 files changed, 18 insertions(+), 13 deletions(-) diff --git a/_themes/rtd-blog/static/local.css b/_themes/rtd-blog/static/local.css index dcb11ac5..8ecb0d1d 100644 --- a/_themes/rtd-blog/static/local.css +++ b/_themes/rtd-blog/static/local.css @@ -3,35 +3,39 @@ h1, h2, h3, h4, h5, h6 margin: 1em 0; } -div.section h1 { +section h1 { font-size: 1.3em; } -div.section h2 { +section h2 { font-size: 1.2em; } -div.section h3 { +section h3 { font-size: 1.1em; } -div.section h4, div.section h5, div.section h6 { +section h4, section h5, section h6 { font-size: 1em; } -div.section ul { - list-style: inside; - margin: 1em 0; +section ul { + list-style: disc; + margin: 1em 0 1em 2em; } -div.section p { - margin: .75rem .5rem; +section ul li p { + margin: 0; +} + +section p { + margin: .75rem 0; line-height: 1.6rem; } -div.section ul li, +section ul li, div.sidebar ul li { - margin: .5em; + margin: .5em 0; line-height: 1.4em; } @@ -81,7 +85,7 @@ dl.docutils dd p, dl dd p { } div.admonition { - padding: .65em; + padding: 1rem 1rem 0.5rem 1rem; margin: 1em 0em; border-radius: .3em; -moz-border-radius: .3em; @@ -91,6 +95,7 @@ div.admonition { div.admonition p.admonition-title { font-weight: bold; + margin-top: 0; } table.footnote { diff --git a/_themes/rtd-blog/static/main.css b/_themes/rtd-blog/static/main.css index 4220cee0..c930d2e2 100644 --- a/_themes/rtd-blog/static/main.css +++ b/_themes/rtd-blog/static/main.css @@ -1094,7 +1094,7 @@ select.dropdown { #content > .wrapper div.col-minor { display: block; overflow: hidden; - padding-left: 1em; + padding-left: 1.5em; } @media (max-width: 1000px) { #content > .wrapper { From ea31c7383ee216a0b67e373d8b933045f2459a5f Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 8 Nov 2022 17:18:28 +0100 Subject: [PATCH 3/9] Fix build issues caused by updated intersphinx references --- newsletter-december-2021.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/newsletter-december-2021.rst b/newsletter-december-2021.rst index 20fa985b..8ed62f60 100644 --- a/newsletter-december-2021.rst +++ b/newsletter-december-2021.rst @@ -34,8 +34,8 @@ New features now they have a dedicated section in the project settings, you can customize the payload, and you can inspect the status of each webhook delivery. - Interested in receiving build notifications on :ref:`Slack ` - or :ref:`Discord `? Now you can! + Interested in receiving build notifications on :ref:`Slack ` + or :ref:`Discord `? Now you can! .. figure:: /img/webhooks-events.png :align: center From 97434487801d2bea46a7663130505c29453cf6a3 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 8 Nov 2022 17:27:06 +0100 Subject: [PATCH 4/9] Fix malformed target --- newsletter-november-2022.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/newsletter-november-2022.rst b/newsletter-november-2022.rst index 98c784d4..e398954d 100644 --- a/newsletter-november-2022.rst +++ b/newsletter-november-2022.rst @@ -49,8 +49,6 @@ We don't have anything firm to announce here yet, but we do plan to be more active in removing these features in the coming months. -.. _november2022_tip_of_the_month - Tip of the month ---------------- From aa03190ad1030ecc7feff357a6458a884ed7cc19 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 8 Nov 2022 17:30:54 +0100 Subject: [PATCH 5/9] Add margins explicitly to .postlist elements --- _themes/rtd-blog/static/local.css | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_themes/rtd-blog/static/local.css b/_themes/rtd-blog/static/local.css index 8ecb0d1d..c4f64d22 100644 --- a/_themes/rtd-blog/static/local.css +++ b/_themes/rtd-blog/static/local.css @@ -112,10 +112,12 @@ table.footnote td.label { .postlist li { list-style: none; + margin-bottom: 2rem; } .postlist p.first, .postlist .ablog-post-title { font-size: 24px; + margin-bottom: 0.5rem; } img.align-center { From c83830c59d5e321b56673624b81613654765bfe1 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 8 Nov 2022 17:39:47 +0100 Subject: [PATCH 6/9] Fix new dl-styled footnotes --- _themes/rtd-blog/static/local.css | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/_themes/rtd-blog/static/local.css b/_themes/rtd-blog/static/local.css index c4f64d22..e603842c 100644 --- a/_themes/rtd-blog/static/local.css +++ b/_themes/rtd-blog/static/local.css @@ -98,12 +98,26 @@ div.admonition p.admonition-title { margin-top: 0; } -table.footnote { - margin: 1em; +dl.footnote { + margin: 0.5rem 0; +} + +dl.footnote dt { + float: left; + margin-left: 1rem; + margin-right: 1rem; + margin-top: 0; } -table.footnote td.label { - padding: .65em; +dl.footnote dd > p:first-child { + margin: 0px; +} + +dl.footnote .brackets:before { + content: "[" +} +dl.footnote .brackets:after { + content: "]" } .postlist { From 4e0d331a0649fab6b5bbe10f94b349c9e89d5679 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 8 Nov 2022 17:44:59 +0100 Subject: [PATCH 7/9] Fix nested list appearing as dl --- announcing-pydoc-io.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/announcing-pydoc-io.rst b/announcing-pydoc-io.rst index 6fee8106..ef8e6ff5 100644 --- a/announcing-pydoc-io.rst +++ b/announcing-pydoc-io.rst @@ -45,7 +45,9 @@ On top of that, we've layered a few different tools: * `sphinx-autoapi`_ which is the tool that takes Python source files and turns them into rST. - * Internally, this uses the `pydocstyle`_ AST parser, which we use for a parse-only representation of the Python files. + + * Internally, this uses the `pydocstyle`_ AST parser, which we use for a parse-only representation of the Python files. + * `pydoc.io`_ is a Django application that is the actual web front-end and documentation building code. * `sphinx-apitheme`_ is the Sphinx theme that powers the actual API listing pages. From 5f1e39bc1fd777b0e8e1dd74fbd37b8a6443194f Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 8 Nov 2022 17:47:43 +0100 Subject: [PATCH 8/9] Re-style figures --- _themes/rtd-blog/static/local.css | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_themes/rtd-blog/static/local.css b/_themes/rtd-blog/static/local.css index e603842c..67c0578c 100644 --- a/_themes/rtd-blog/static/local.css +++ b/_themes/rtd-blog/static/local.css @@ -148,14 +148,14 @@ div.highlight pre { } /* Optimize figure CSS */ -div.figure { +figure { text-align: center; margin: 2em 0; } -div.figure img { +figure img { max-width: 100%; } -div.figure p.caption { +figure figcaption { font-size: 85%; line-height: 1.4; margin-left: 2.5rem; From 417afae21583030febe0f133a20a68c64b7b73f0 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 8 Nov 2022 23:36:56 +0100 Subject: [PATCH 9/9] Switch footnotes to use table layout --- _themes/rtd-blog/static/local.css | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/_themes/rtd-blog/static/local.css b/_themes/rtd-blog/static/local.css index 67c0578c..640f4a28 100644 --- a/_themes/rtd-blog/static/local.css +++ b/_themes/rtd-blog/static/local.css @@ -100,16 +100,20 @@ div.admonition p.admonition-title { dl.footnote { margin: 0.5rem 0; + display: table; } dl.footnote dt { - float: left; + display: table-cell; + white-space: nowrap; + width: 1%; margin-left: 1rem; margin-right: 1rem; margin-top: 0; } dl.footnote dd > p:first-child { + display: table-cell; margin: 0px; }