From 765c5a5e28a42d910cad3ada7f18a4ffc56427a7 Mon Sep 17 00:00:00 2001 From: Fabian Vogt Date: Wed, 14 Feb 2024 15:18:56 +0100 Subject: [PATCH] Improve documentation generation With Sphinx >= 6.0.0, jQuery is no longer included but the rtd theme's search functionality needs it. The theme was changed to load sphinxcontrib-jquery automatically with https://github.com/readthedocs/sphinx_rtd_theme/pull/1399, but kiwi broke this fix by loading the theme in the wrong way. Now that the theme is loaded properly, the search functionality also works with newer versions of sphinx again and the version pinning can be lifted. This Fixes: #2462 --- .virtualenv.dev-requirements.txt | 2 +- doc/source/.static/css/custom.css | 447 ------------------------------ doc/source/conf.py | 7 +- 3 files changed, 3 insertions(+), 453 deletions(-) delete mode 100644 doc/source/.static/css/custom.css diff --git a/.virtualenv.dev-requirements.txt b/.virtualenv.dev-requirements.txt index 5c1e5cadbdd..7687ec92ef6 100644 --- a/.virtualenv.dev-requirements.txt +++ b/.virtualenv.dev-requirements.txt @@ -38,7 +38,7 @@ types-simplejson generateDS==2.29.24 # for building documentation -sphinx==5.0.0 +sphinx>=5.0.0 git+https://github.com/openSUSE/rstxml2docbook.git@feature/kiwi diff --git a/doc/source/.static/css/custom.css b/doc/source/.static/css/custom.css deleted file mode 100644 index d11af6d274c..00000000000 --- a/doc/source/.static/css/custom.css +++ /dev/null @@ -1,447 +0,0 @@ -/*---------------------------------------- - Global ------------------------------------------*/ -table { - font-family:arial, helvetica, sans-serif; - font-size:12px; -} - -/*-------------------------------------------- - Source code in the instance, source or - annotations. ---------------------------------------------*/ -span.tokenElement { - color: #000096; - background-color:inherit; -} -span.tokenAttrName { - color: #F5844C; - background-color:inherit; -} -span.tokenAttrValue { - color: #993300; - background-color:inherit; -} -span.tokenIndent { - color: #000000; - background-color:inherit; -} -span.tokenText { - color: #000000; - background-color:inherit; - white-space: normal; -} -span.tokenComment { - color: #006400; - background-color:inherit; -} -span.tokenCDATA { - color: #008C00; - background-color:inherit; -} -span.tokenPI { - color: #8B26C9; - background-color:inherit; -} -span.tokenEntity { - color: #969600; - background-color:inherit; -} -span.qname{ - color:#000096; - background-color:inherit; -} - -/*----------------------------------------- - Documentation sections. -------------------------------------------*/ - -div.componentTitle { - font-size:1.4em; - font-weight:bold; - text-align:left; - margin-top:1.4em; - margin-bottom:0.7em; -} -div.componentTitle{ -/* color:rgb(255, 160, 100);*/ - color:#333333; - background-color:inherit; -} - - -/* Tables. */ - -td, th { - padding:2px 2px 2px 5px; - text-align:left; - vertical-align:top; -} - -tr > th { - background-color:#C4DAF4; - color:inherit; -} - -/* Contrast for the titles*/ -table.component { - width:100%; - border-spacing:1px; -} - -@media print{ - table.component{ - border:1px solid gray; - border-collapse:collapse; - } - - table.component td{ - border:1px solid gray; - } -} - -table.component td.firstColumn{ - background-color:#C4DAF4; - color:black; - width:12%; -} - -table.component table td.firstColumn{ - border:none; - background-color:#EAF1FB; - color: inherit; -} - -td.firstColumn b{ - font-weight:normal; -} - - -/* The Name and Expand/Collapse control are on the same line - but at different ends.*/ -td.firstColumn div.floatLeft{ - float:left; -} -td.firstColumn div.floatRight{ - float:right; -} - -/* Subtables */ -table.component table{ - width:100%; -} -table.component table, -table.component table td, -table.component table th{ - border:0; -} - - -/* Properties table */ -table.propertiesTable { - border-spacing:1px; -} -table.propertiesTable td.firstColumn{ - width:140px; - text-transform:capitalize; -} -/* Used by table */ -table.usedByTable { - border-spacing:1px; -} -table.usedByTable td.firstColumn{ - width:140px; - text-transform:capitalize; -} - -/* Facets table*/ -table.facetsTable { - border-spacing:1px; -} -table.facetsTable td.firstColumn{ - width:140px; - text-transform:capitalize; -} - -/* Attributes table */ -table.attributesTable { - border-spacing:1px; -} -table.attributesTable th{ - font-weight:normal; -} -table.attributesTable tr:hover{ - color:inherit; - background-color:#EAF1FB; -} - - -/* Identity constraints table */ -table.identityConstraintsTable { - border-spacing:1px; -} -table.identityConstraintsTable th{ - font-weight:normal; -} -table.identityConstraintsTable tr:hover{ - color:inherit; - background-color:#EAF1FB; -} - - - -/*--------------------------------------- - The diagram. -----------------------------------------*/ -table.component td.diagram { - background-color:white; - color:inherit; -} - -/* This table is a workaround for an IE bug regarding pre-wrap */ -table.preWrapContainer, -table.preWrapContainer td{ - border:0; - margin:0; - padding:0; -} - - -/* Annotations. */ -div.annotation{ -} -div.annotation pre{ - font-family:arial, helvetica, sans-serif; - margin:0; -} -div.annotation, -div.annotation table, -div.annotation table td{ - margin:0; - padding:0; -} - -/* Hierarchy */ -ul > li{ - list-style:none; -} - -ul { - margin:2px; - padding:0; -} - -ul ul li { - padding-left:10px; - - list-style-image:url('images/hierarchy_arrow.gif'); - list-style-position:inside; -} - -/*------------------------------------- - Rounded tables. ----------------------------------------*/ -table.rt, -table.rt_with_bg{ - border-collapse:collapse; - border-spacing:0; - width:100%; -} -table.rt_with_bg{ - /*background-color:#C0F0A0;*/ - background-color:white; - color:inherit; -} - - -.rt_cornerTopLeft{ - background-color:transparent; - background-repeat:no-repeat; - background-position:right; - width:8px; - height:8px; - margin:0; - padding:0; -} -.rt_cornerTopLeft{ - background-image:url('images/corner_top_left.gif'); -} - - -.rt_cornerBottomLeft{ - background-color:transparent; - background-repeat:no-repeat; - background-position:right; - width:8px; - height:8px; - margin:0; - padding:0; -} -.rt_cornerBottomLeft{ - background-image:url('images/corner_bottom_left.gif'); -} - - -.rt_cornerTopRight{ - background-color:transparent; - background-repeat:no-repeat; - width:8px; - height:8px; - margin:0; - padding:0; - -} -.rt_cornerTopRight{ - background-image:url('images/corner_top_right.gif'); -} - - -.rt_cornerBottomRight{ - background-color:transparent; - background-repeat:no-repeat; - width:8px; - height:8px; - margin:0; - padding:0; - -} -.rt_cornerBottomRight{ - background-image:url('images/corner_bottom_right.gif'); -} - - -.rt_content{ - background-color:white; - color:inherit; - width:auto; - margin:0; - padding:0; -} - - -.rt_lineLeft{ - background-color:transparent; - background-repeat:repeat-y; - background-position:right; - width:8px; - margin:0; - padding:0; - -} -.rt_lineLeft{ - background-image:url('images/line_left.gif'); -} - - -.rt_lineRight{ - background-repeat:repeat-y; - width:8px; - margin:0; - padding:0; -} -.rt_lineRight{ - background-image:url('images/line_right.gif'); -} - - -.rt_lineTop{ - background-color:transparent; - background-repeat:repeat-x; - height:8px; - width:auto; - margin:0; - padding:0; -} -.rt_lineTop{ - background-image:url('images/line_top.gif'); -} - -.rt_lineBottom{ - background-color:transparent; - background-repeat:repeat-x; - height:8px; - width:auto; - margin:0; - padding:0; -} -.rt_lineBottom{ - background-image:url('images/line_bottom.gif'); -} - - -/* -------------------------------------- - Controls for bulk showing/hidding sections - from the documentation. -----------------------------------------*/ -.globalControls h3{ - margin:0.1em; - font-size:1.2em; -} - -.globalControls table td{ - padding:0; - margin:0; -} - -.globalControls{ - position:fixed; - left:0; - background-color:transparent; - padding-left:0.5em; - padding-right:0.5em; - padding-bottom:0.5em; - width:190px; -} - -@media print{ - .globalControls{ - display:none; - } -} - -/* Expand/collapse of a single section. */ -input.control { - text-align:center; - vertical-align:middle; - padding:0; - padding-right:3px; - padding-bottom:2px; - -} - - -/* close button */ -td.rt_content div span input{ - font-size:0.8em; -} - -@media print{ - input.control{ - display:none; - } -} - -/*------------------------------------------ - The second level of index. Floating DIVs --------------------------------------------*/ -.toc { -} -.toc div.verticalLayout, div.horizontalLayout{ - float:left; - display:block; - - background-color:white; - color:inherit; - - min-width:130px; - min-height:50px; - - padding:0.5em; -} - -.toc div.componentGroupTitle{ - font-weight:bold; - margin-bottom:0.5em; - color:black; - background-color:inherit; -} diff --git a/doc/source/conf.py b/doc/source/conf.py index 7d5a43d3d6c..ab063401a34 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -7,7 +7,6 @@ import sys from os.path import abspath, dirname, join, normpath import shlex -import sphinx_rtd_theme # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -32,7 +31,8 @@ 'sphinx.ext.todo', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', - 'sphinx.ext.autodoc' + 'sphinx.ext.autodoc', + 'sphinx_rtd_theme' ] docopt_ignore = [ @@ -61,7 +61,6 @@ def setup(app): app.add_config_value('prolog_replacements', {}, True) app.connect('source-read', prologReplace) app.connect("autodoc-process-docstring", remove_module_docstring) - app.add_css_file('css/custom.css') prolog_replacements = { @@ -196,8 +195,6 @@ def setup(app): html_theme = "sphinx_rtd_theme" -html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] - html_static_path = ['.static'] html_theme_options = {