jenkins-bot has submitted this change. ( https://gerrit.wikimedia.org/r/c/pywikibot/core/+/859448 )

Change subject: [doc] Improve documentation look and feel ......................................................................

[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(-)

Approvals: Xqt: Looks good to me, approved jenkins-bot: Verified

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