From d89c557a10fc9eafd03848e8a8a4c5952a23803e Mon Sep 17 00:00:00 2001 From: Benjamin Balder Bach Date: Tue, 8 Nov 2022 23:39:32 +0100 Subject: [PATCH] Build updates! (#188) * Update to latest Sphinx, ablog and fail on warnings. Fix some broken intersphinx. Apply styles for ablog that aligns headers with post ul list. * Updates to CSS, reflecting more docutils DOM changes * Fix build issues caused by updated intersphinx references * Fix malformed target * Add margins explicitly to .postlist elements * Fix new dl-styled footnotes * Fix nested list appearing as dl * Re-style figures * Switch footnotes to use table layout --- .readthedocs.yml | 1 + _themes/rtd-blog/static/local.css | 75 ++++++++++++++++++++++--------- _themes/rtd-blog/static/main.css | 2 +- announcing-pydoc-io.rst | 4 +- conf.py | 4 +- embed-api-v3.rst | 4 +- newsletter-december-2021.rst | 4 +- newsletter-november-2022.rst | 2 - requirements.txt | 10 ++--- 9 files changed, 69 insertions(+), 37 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..640f4a28 100644 --- a/_themes/rtd-blog/static/local.css +++ b/_themes/rtd-blog/static/local.css @@ -1,32 +1,41 @@ -div.section h1 { +h1, h2, h3, h4, h5, h6 +{ + margin: 1em 0; +} + +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; +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; } @@ -76,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; @@ -86,25 +95,49 @@ div.admonition { div.admonition p.admonition-title { font-weight: bold; + margin-top: 0; } -table.footnote { - margin: 1em; +dl.footnote { + margin: 0.5rem 0; + display: table; +} + +dl.footnote dt { + 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; } -table.footnote td.label { - padding: .65em; +dl.footnote .brackets:before { + content: "[" +} +dl.footnote .brackets:after { + content: "]" +} + +.postlist { + margin: 1em 0; } .postlist li { list-style: none; + margin-bottom: 2rem; } -.postlist p.first { +.postlist p.first, .postlist .ablog-post-title { font-size: 24px; + margin-bottom: 0.5rem; } - img.align-center { display: block; margin: 0 auto; @@ -119,14 +152,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; 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 { 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. diff --git a/conf.py b/conf.py index 0060d78b..22bd33dc 100644 --- a/conf.py +++ b/conf.py @@ -81,8 +81,6 @@ )) templates_path.append(ablog.get_html_templates_path()) -html4_writer = True - if os.environ.get('READTHEDOCS', None) == 'True': skip_pickling = True @@ -98,7 +96,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/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 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 ---------------- 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