From 356cb052849efe22740dde8baff18e2a4a056667 Mon Sep 17 00:00:00 2001
From: =?utf8?q?G=C3=BCnter=20Milde?= <milde@users.sf.net>
Date: Thu, 23 Jun 2022 00:19:08 +0200
Subject: [PATCH] Documentation update

Adapt to Sphinx 3.4.3 and Docutils "html5" writer.
---
 doc/_static/pylit-sphinx.css | 55 ++++++++++++++++++++++++++++++++++++++++----
 doc/conf.py                  | 17 +++++---------
 doc/index.txt                |  8 ++++---
 3 files changed, 62 insertions(+), 18 deletions(-)

diff --git a/doc/_static/pylit-sphinx.css b/doc/_static/pylit-sphinx.css
index 1c603c5..48c13c9 100644
--- a/doc/_static/pylit-sphinx.css
+++ b/doc/_static/pylit-sphinx.css
@@ -576,7 +576,7 @@ a.headerlink:hover {
 }
 
 div.body p, div.body dd, div.body li {
-    text-align: justify;
+    text-align: left;
     line-height: 130%;
 }
 
@@ -689,9 +689,6 @@ table.field-list td, table.field-list th {
     border: 0 !important;
 }
 
-table.footnote td, table.footnote th {
-    border: 0 !important;
-}
 
 .field-list ul {
     margin: 0;
@@ -810,6 +807,56 @@ tt.xref, a tt {
     font-weight: bold;
 }
 
+/* Footnotes and Citations */
+.footnote {
+  font-size: small;
+}
+.footnote, .citation { margin: 1em 0; } /* default paragraph skip (Firefox) */
+/* hanging indent */
+.citation { padding-left: 2em; }
+.footnote { padding-left: 1.7em; }
+.footnote.superscript { padding-left: 0.9em; }
+.citation > .label { margin-left: -2em; }
+.footnote > .label { margin-left: -1.7em; }
+.footnote.superscript > .label { margin-left: -0.9em; }
+
+.footnote > .label + *,
+.citation > .label + * {
+  display: inline-block;
+  margin-top: 0;
+  vertical-align: top;
+}
+.footnote > .backrefs + *,
+.citation > .backrefs + * {
+  margin-top: 0;
+}
+.footnote > .label + p, .footnote > .backrefs + p,
+.citation > .label + p, .citation > .backrefs + p {
+  display: inline;
+  vertical-align: inherit;
+}
+
+.backrefs > a { font-style: italic; }
+
+/* superscript footnotes */
+a[role="doc-noteref"].superscript,
+.footnote.superscript > .label,
+.footnote.superscript > .backrefs {
+  vertical-align: super;
+  font-size: smaller;
+  line-height: 1;
+}
+a[role="doc-noteref"].superscript > .fn-bracket,
+.footnote.superscript > .label > .fn-bracket {
+  /* hide brackets in display but leave for copy/paste */
+  display: inline-block;
+  width: 0;
+  overflow: hidden;
+}
+[role="doc-noteref"].superscript + [role="doc-noteref"].superscript {
+  padding-left: 0.15em; /* separate consecutive footnote references */
+  /* TODO: unfortunately, "+" also selects with text between the references. */
+}
 .footnote:target  { background-color: #ffa }
 
 h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
diff --git a/doc/conf.py b/doc/conf.py
index c4b88ec..0c2baed 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -1,5 +1,3 @@
-## -*- coding: utf-8 -*-
-  
 # conf.py -- Sphinx configuration for PyLit
 # =========================================
 # 
@@ -77,17 +75,15 @@ today_fmt = '%B %d, %Y'
 # to the source directory, using slashes as directory separators on all
 # platforms.
 
-exclude_patterns = ['**/.svn']
-
-# Deprecated since version 1.0: Use exclude_patterns instead.
-# exclude_dirnames = [".svn"]
+exclude_patterns = ['**/filename-extensions.txt', 
+                    '**/hello_with_doctest.py.txt']
 
 # The name of the default domain. Can also be None to disable a default
 # domain. The default is 'py'. Those objects in other domains (whether the
 # domain name is given explicitly, or selected by a default-domain directive)
-# require the domain name explicitly prepended when named.
+# require the domain name explicitly prepended when named. ::
 
-# primary_domain = 'py'
+#primary_domain = 'py'
 primary_domain = None
 
 
@@ -122,7 +118,6 @@ add_function_parentheses = True
 # <http://pygments.org/demo/>`_ pages that offer a drop-down list to select
 # the style, e.g. http://pygments.org/demo/1444/
 # 
-# 
 # ::
 
 #pygments_style = 'sphinx' 
@@ -136,7 +131,7 @@ pygments_style = 'friendly'
 # given in html_static_path::
 
 html_style = 'pylit-sphinx.css'
-# html_style = 'sphinxdoc.css'
+#html_style = 'default.css'
 
 # Options to the theme, like a sidebar that is visible even when
 # scrolling (TODO: how to get this to work (maybe just update Spinx)?)::
@@ -183,7 +178,7 @@ html_last_updated_fmt = '%b %d, %Y'
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities::
 
-#html_use_smartypants = True
+html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names::
 
diff --git a/doc/index.txt b/doc/index.txt
index 5148df1..62b7550 100644
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -1,5 +1,3 @@
-.. -*- rst-mode -*-
-
 PyLit
 *****
 
@@ -10,6 +8,10 @@ PyLit
    The idea is that you do not document programs (after the fact), but
    write documents that *contain* the programs. [1]_
 
+.. meta::
+   :description: Literate Programming with reStructuredText
+   :keywords: reStructuredText, Docutils, software development
+
 Features
 --------
 
@@ -69,7 +71,7 @@ Copyright
 ---------
 
 Copyright
-  © 2005, 2009 Günter Milde.
+  © 2005, 2007, 2015, 2021 Günter Milde.
 
 License
   PyLit is `free software`_, released under the `GNU General Public License`_
-- 
2.11.4.GIT