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 · Nov 8, 2022 · d89c557 · d89c557
1 parent cf8d50c
commit d89c557
Show file tree

Hide file tree

Showing 9 changed files with 69 additions and 37 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 <guides/embedding-content:embedding content from your documentation>`.
+:ref:`embed content from pages hosted outside Read the Docs <readthedocs:guides/embedding-content:embedding content from your documentation>`.
 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 <guides/reproducible-builds>`:
+:doc:`declare it as part of your dependencies <readthedocs:guides/reproducible-builds>`:
 
 .. code-block::
    :caption: requirements.txt

diff --git 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 <readthedocs:build-notifications:slack>`
-  or :ref:`Discord <readthedocs:build-notifications:discord>`? Now you can!
+  Interested in receiving build notifications on :ref:`Slack <readthedocs:guides/build-notifications:slack>`
+  or :ref:`Discord <readthedocs:guides/build-notifications:discord>`? Now you can!
 
 .. figure:: /img/webhooks-events.png
    :align: center

diff --git 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
@@ -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
-Original file line number
+Diff line change
@@ Expand Up / @@ -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
     ----------------
@@ Expand Down @@