[doc] Improve documentation look and feel

* add the sphinx-opengraph extension
* customize edit link to allow readers to access source RST files in
  gerrit easily
* allow users to navigate between pages using arrow keys (left for 
previous, right for next)
* set pygments light style explicitly
* add more prominent highlighting on a:hover
* ensure the logo does not take too much space
* add make mini to Makefile as a way to quickly rebuild docs after 
  minor changes

Bug: T322212
Change-Id: Ifde05319db3591ff3423b21c66d92cbb1f06e8b5
---
M .gitignore
M docs/make.bat
M docs/conf.py
M docs/requirements.txt
M docs/_static/css/pywikibot.css
M docs/Makefile
6 files changed, 67 insertions(+), 39 deletions(-)

diff --git a/.gitignore b/.gitignore
index 9d20600..965b100 100644
--- a/.gitignore
+++ b/.gitignore
@@ -23,4 +23,5 @@
 docs/_build/
 /scripts/userscripts/*
 !/scripts/userscripts/__init__.py
-.vscode/
\ No newline at end of file
+.vscode/
+**/.DS_Store
diff --git a/docs/Makefile b/docs/Makefile
index 6f63c8c..1a49959 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -2,7 +2,8 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -a
+SPHINXOPTS    = -a -j auto
+SPHINXOPTSMINI= -j auto
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = Pywikibot
 SOURCEDIR     = .
@@ -12,6 +13,11 @@
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+# make mini only rebuilds what has changed
+# make html and others rebuild all content (because of the -a flag)
+mini:
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTSMINI) $(O)
+
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
diff --git a/docs/_static/css/pywikibot.css b/docs/_static/css/pywikibot.css
index 56e8d93..6721511 100644
--- a/docs/_static/css/pywikibot.css
+++ b/docs/_static/css/pywikibot.css
@@ -1,43 +1,31 @@
 /** css/pywikibot.css **/
 
-/* This line is theme specific - it includes the base theme CSS */
-@import '../nature.css';  /* for Nature */
-
-
-div.related {
-    background-color: #396;
-    line-height: 32px;
-    color: #fff;
-    text-shadow: 0px 1px 0 #444;
-    font-size: 0.9em;
+/** logo slightly smaller than default to preserve vertical space **/
+.sidebar-logo {
+    max-width: 75%;
 }
 
-a:hover {
-    color: #900;
-    text-decoration: underline;
+/** brand text in the sidebar smaller than default **/
+.sidebar-brand-text {
+    font-size: 1rem;
 }
 
-a.headerlink {
-    color: #069;
-    font-size: 0.8em;
-    padding: 0 4px 0 4px;
+/** border highlight for links in article content **/
+article a:hover {
+    box-shadow: 0 0 0 .125rem var(--color-link);
+    border-radius: .125rem;
     text-decoration: none;
+    padding-bottom: .110rem;
 }
 
-a.headerlink:hover {
-    background-color: #069;
-    color: white;
+/** better readability of toctree captions **/
+.toctree-wrapper .caption {
+    font-weight: bolder;
+    margin-bottom: .5rem !important;
 }
-code.xref {
-    color: #069;
-    font-size: 1.2em
+
+/** disable centering of tables by default in regular content **/
+table.align-default {
+    margin-left: unset;
+    margin-right: unset;
 }
-code.xref:hover {
-    color: #900;
-}
-div.sphinxsidebar {
-    width: 250px
-}
-div.bodywrapper {
-  margin: 0 0 0 250px;
-}
\ No newline at end of file
diff --git a/docs/conf.py b/docs/conf.py
index b28e251..b5a4fe3 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -57,6 +57,7 @@
     'sphinx.ext.napoleon',
     'sphinx.ext.todo',
     'sphinx.ext.viewcode',
+    'sphinxext.opengraph',
 ]
 
 
@@ -131,7 +132,8 @@
 # show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = 'default'
+
 
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
@@ -154,7 +156,7 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
@@ -222,6 +224,12 @@
 #
 html_split_index = True
 
+docs_url = 'https://gerrit.wikimedia.org/g/pywikibot/core/%2B/HEAD/docs/'
+html_theme_options = {
+    'source_edit_link': docs_url + '{filename}',
+    'navigation_with_keys': True,
+}
+
 # If true, links to the reST sources are added to the pages.
 #
 # html_show_sourcelink = True
@@ -377,7 +385,9 @@
 
 # Pywikibot theme style
 html_permalinks_icon = '#'
-# html_style = 'css/pywikibot.css'
+html_css_files = [
+    'css/pywikibot.css',
+]
 
 
 extlinks = {
diff --git a/docs/make.bat b/docs/make.bat
index 8bacfe3..4ea5f91 100644
--- a/docs/make.bat
+++ b/docs/make.bat
@@ -10,6 +10,7 @@
 set SOURCEDIR=.

 set BUILDDIR=_build

 set SPHINXPROJ=Pywikibot

+set SPHINXOPTS=-j auto

 
 if "%1" == "" goto help

 
diff --git a/docs/requirements.txt b/docs/requirements.txt
index e287d85..61d54ac 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,5 +1,6 @@
 # This is a PIP requirements file for building Sphinx documentation of pywikibot
 # requirements.txt is also needed
-furo
 sphinx >= 5.2.3
-rstcheck >=6.1.0
\ No newline at end of file
+rstcheck >=6.1.0
+sphinxext-opengraph >= 0.7.2
+furo >= 2022.9.29

