diff options
| -rw-r--r-- | Documentation/conf.py | 206 | ||||
| -rw-r--r-- | Documentation/doc-guide/sphinx.rst | 16 | ||||
| -rw-r--r-- | Documentation/sphinx-static/custom.css | 28 | ||||
| -rw-r--r-- | Documentation/sphinx/requirements.txt | 1 | ||||
| -rwxr-xr-x | scripts/kernel-doc | 54 | ||||
| -rwxr-xr-x | scripts/sphinx-pre-install | 8 |
6 files changed, 93 insertions, 220 deletions
diff --git a/Documentation/conf.py b/Documentation/conf.py index b50c85083149..6ab47833ab6c 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -194,6 +194,24 @@ finally: else: version = release = "unknown version" +# +# HACK: there seems to be no easy way for us to get at the version and +# release information passed in from the makefile...so go pawing through the +# command-line options and find it for ourselves. +# +def get_cline_version(): + c_version = c_release = '' + for arg in sys.argv: + if arg.startswith('version='): + c_version = arg[8:] + elif arg.startswith('release='): + c_release = arg[8:] + if c_version: + if c_release: + return c_version + '-' + c_release + return c_version + return version # Whatever we came up with before + # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # @@ -247,7 +265,7 @@ highlight_language = 'none' # a list of builtin themes. # Default theme -html_theme = 'sphinx_rtd_theme' +html_theme = 'alabaster' html_css_files = [] if "DOCS_THEME" in os.environ: @@ -279,7 +297,7 @@ if html_theme == 'sphinx_rtd_theme' or html_theme == 'sphinx_rtd_dark_mode': html_css_files.append('theme_rtd_colors.css') except ImportError: - html_theme = 'classic' + html_theme = 'alabaster' if "DOCS_CSS" in os.environ: css = os.environ["DOCS_CSS"].split(" ") @@ -295,127 +313,28 @@ if major <= 1 and minor < 8: for l in html_css_files: html_context['css_files'].append('_static/' + l) -if html_theme == 'classic': +if html_theme == 'alabaster': html_theme_options = { - 'rightsidebar': False, - 'stickysidebar': True, - 'collapsiblesidebar': True, - 'externalrefs': False, - - 'footerbgcolor': "white", - 'footertextcolor': "white", - 'sidebarbgcolor': "white", - 'sidebarbtncolor': "black", - 'sidebartextcolor': "black", - 'sidebarlinkcolor': "#686bff", - 'relbarbgcolor': "#133f52", - 'relbartextcolor': "white", - 'relbarlinkcolor': "white", - 'bgcolor': "white", - 'textcolor': "black", - 'headbgcolor': "#f2f2f2", - 'headtextcolor': "#20435c", - 'headlinkcolor': "#c60f0f", - 'linkcolor': "#355f7c", - 'visitedlinkcolor': "#355f7c", - 'codebgcolor': "#3f3f3f", - 'codetextcolor': "white", - - 'bodyfont': "serif", - 'headfont': "sans-serif", + 'description': get_cline_version(), + 'font_size': '10pt', + 'page_width': '65em', + 'sidebar_width': '15em', } sys.stderr.write("Using %s theme\n" % html_theme) -# Theme options are theme-specific and customize the look and feel of a theme -# 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 = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# "<project> v<release> documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['sphinx-static'] -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -#html_extra_path = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#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 = False # Custom sidebar templates, maps document names to template names. -# Note that the RTD theme ignores this. -html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a <link> tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr' -#html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# Now only 'ja' uses this config value -#html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -#html_search_scorer = 'scorer.js' +# Note that the RTD theme ignores this +html_sidebars = { '**': ["about.html", 'searchbox.html', 'localtoc.html', 'sourcelink.html']} # Output file base name for HTML help builder. htmlhelp_basename = 'TheLinuxKerneldoc' @@ -558,19 +477,6 @@ texinfo_documents = [ 'Miscellaneous'), ] -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False - - # -- Options for Epub output ---------------------------------------------- # Bibliographic Dublin Core info. @@ -579,67 +485,9 @@ epub_author = author epub_publisher = author epub_copyright = copyright -# The basename for the epub file. It defaults to the project name. -#epub_basename = project - -# The HTML theme for the epub output. Since the default themes are not -# optimized for small screen space, using the same theme for HTML and epub -# output is usually not wise. This defaults to 'epub', a theme designed to save -# visual space. -#epub_theme = 'epub' - -# The language of the text. It defaults to the language option -# or 'en' if the language is not set. -#epub_language = '' - -# The scheme of the identifier. Typical schemes are ISBN or URL. -#epub_scheme = '' - -# The unique identifier of the text. This can be a ISBN number -# or the project homepage. -#epub_identifier = '' - -# A unique identification for the text. -#epub_uid = '' - -# A tuple containing the cover image and cover page html template filenames. -#epub_cover = () - -# A sequence of (type, uri, title) tuples for the guide element of content.opf. -#epub_guide = () - -# HTML files that should be inserted before the pages created by sphinx. -# The format is a list of tuples containing the path and title. -#epub_pre_files = [] - -# HTML files that should be inserted after the pages created by sphinx. -# The format is a list of tuples containing the path and title. -#epub_post_files = [] - # A list of files that should not be packed into the epub file. epub_exclude_files = ['search.html'] -# The depth of the table of contents in toc.ncx. -#epub_tocdepth = 3 - -# Allow duplicate toc entries. -#epub_tocdup = True - -# Choose between 'default' and 'includehidden'. -#epub_tocscope = 'default' - -# Fix unsupported image types using the Pillow. -#epub_fix_images = False - -# Scale large images. -#epub_max_image_width = 0 - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#epub_show_urls = 'inline' - -# If false, no index is generated. -#epub_use_index = True - #======= # rst2pdf # diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst index c708cec889af..23edb427e76f 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -147,11 +147,9 @@ section of ``make help``. The generated documentation is placed in format-specific subdirectories under ``Documentation/output``. To generate documentation, Sphinx (``sphinx-build``) must obviously be -installed. For prettier HTML output, the Read the Docs Sphinx theme -(``sphinx_rtd_theme``) is used if available. For PDF output you'll also need -``XeLaTeX`` and ``convert(1)`` from ImageMagick -(https://www.imagemagick.org).\ [#ink]_ -All of these are widely available and packaged in distributions. +installed. For PDF output you'll also need ``XeLaTeX`` and ``convert(1)`` +from ImageMagick (https://www.imagemagick.org).\ [#ink]_ All of these are +widely available and packaged in distributions. To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose @@ -160,12 +158,8 @@ output. It is also possible to pass an extra DOCS_CSS overlay file, in order to customize the html layout, by using the ``DOCS_CSS`` make variable. -By default, the build will try to use the Read the Docs sphinx theme: - - https://github.com/readthedocs/sphinx_rtd_theme - -If the theme is not available, it will fall-back to the classic one. - +By default, the "Alabaster" theme is used to build the HTML documentation; +this theme is bundled with Sphinx and need not be installed separately. The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable. There is another make variable ``SPHINXDIRS``, which is useful when test diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css new file mode 100644 index 000000000000..9b36f7abd24f --- /dev/null +++ b/Documentation/sphinx-static/custom.css @@ -0,0 +1,28 @@ +/* SPDX-License-Identifier: GPL-2.0 */ +/* + * CSS tweaks for the Alabaster theme + */ + +/* Shrink the headers a bit */ +div.body h1 { font-size: 180%; } +div.body h2 { font-size: 150%; } +div.body h3 { font-size: 130%; } + +/* Tighten up the layout slightly */ +div.body { padding: 0 15px 0 10px; } +div.sphinxsidebarwrapper { padding: 1em 0.4em; } +/* Tweak document margins and don't force width */ +div.document { + margin: 20px 10px 0 10px; + width: auto; +} + +/* + * Parameters for the display of function prototypes and such included + * from C source files. + */ +dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0f3; } +/* indent lines 2+ of multi-line function prototypes */ +dl.function dt { margin-left: 10em; text-indent: -10em; } +dt.sig-object { font-size: larger; } +div.kernelindent { margin-left: 2em; margin-right: 4em; } diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt index 2c573541ab71..335b53df35e2 100644 --- a/Documentation/sphinx/requirements.txt +++ b/Documentation/sphinx/requirements.txt @@ -1,4 +1,3 @@ # jinja2>=3.1 is not compatible with Sphinx<4.0 jinja2<3.1 -sphinx_rtd_theme Sphinx==2.4.4 diff --git a/scripts/kernel-doc b/scripts/kernel-doc index aea04365bc69..11bafc8e85ab 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -866,48 +866,53 @@ sub output_function_rst(%) { print "\n"; } - print "**Parameters**\n\n"; + # + # Put our descriptive text into a container (thus an HTML <div>) to help + # set the function prototypes apart. + # + print ".. container:: kernelindent\n\n"; $lineprefix = " "; + print $lineprefix . "**Parameters**\n\n"; foreach $parameter (@{$args{'parameterlist'}}) { my $parameter_name = $parameter; $parameter_name =~ s/\[.*//; $type = $args{'parametertypes'}{$parameter}; if ($type ne "") { - print "``$type``\n"; + print $lineprefix . "``$type``\n"; } else { - print "``$parameter``\n"; + print $lineprefix . "``$parameter``\n"; } print_lineno($parameterdesc_start_lines{$parameter_name}); + $lineprefix = " "; if (defined($args{'parameterdescs'}{$parameter_name}) && $args{'parameterdescs'}{$parameter_name} ne $undescribed) { output_highlight_rst($args{'parameterdescs'}{$parameter_name}); } else { - print " *undescribed*\n"; + print $lineprefix . "*undescribed*\n"; } + $lineprefix = " "; print "\n"; } - $lineprefix = $oldprefix; output_section_rst(@_); + $lineprefix = $oldprefix; } sub output_section_rst(%) { my %args = %{$_[0]}; my $section; my $oldprefix = $lineprefix; - $lineprefix = ""; foreach $section (@{$args{'sectionlist'}}) { - print "**$section**\n\n"; + print $lineprefix . "**$section**\n\n"; print_lineno($section_start_lines{$section}); output_highlight_rst($args{'sections'}{$section}); print "\n"; } print "\n"; - $lineprefix = $oldprefix; } sub output_enum_rst(%) { @@ -915,6 +920,7 @@ sub output_enum_rst(%) { my ($parameter); my $oldprefix = $lineprefix; my $count; + my $outer; if ($sphinx_major < 3) { my $name = "enum " . $args{'enum'}; @@ -924,22 +930,25 @@ sub output_enum_rst(%) { print "\n\n.. c:enum:: " . $name . "\n\n"; } print_lineno($declaration_start_line); - $lineprefix = " "; + $lineprefix = " "; output_highlight_rst($args{'purpose'}); print "\n"; - print "**Constants**\n\n"; - $lineprefix = " "; + print ".. container:: kernelindent\n\n"; + $outer = $lineprefix . " "; + $lineprefix = $outer . " "; + print $outer . "**Constants**\n\n"; foreach $parameter (@{$args{'parameterlist'}}) { - print "``$parameter``\n"; + print $outer . "``$parameter``\n"; + if ($args{'parameterdescs'}{$parameter} ne $undescribed) { output_highlight_rst($args{'parameterdescs'}{$parameter}); } else { - print " *undescribed*\n"; + print $lineprefix . "*undescribed*\n"; } print "\n"; } - + print "\n"; $lineprefix = $oldprefix; output_section_rst(@_); } @@ -982,18 +991,19 @@ sub output_struct_rst(%) { } } print_lineno($declaration_start_line); - $lineprefix = " "; + $lineprefix = " "; output_highlight_rst($args{'purpose'}); print "\n"; - print "**Definition**\n\n"; - print "::\n\n"; + print ".. container:: kernelindent\n\n"; + print $lineprefix . "**Definition**::\n\n"; my $declaration = $args{'definition'}; - $declaration =~ s/\t/ /g; - print " " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration };\n\n"; + $lineprefix = $lineprefix . " "; + $declaration =~ s/\t/$lineprefix/g; + print $lineprefix . $args{'type'} . " " . $args{'struct'} . " {\n$declaration" . $lineprefix . "};\n\n"; - print "**Members**\n\n"; $lineprefix = " "; + print $lineprefix . "**Members**\n\n"; foreach $parameter (@{$args{'parameterlist'}}) { ($parameter =~ /^#/) && next; @@ -1003,8 +1013,10 @@ sub output_struct_rst(%) { ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; $type = $args{'parametertypes'}{$parameter}; print_lineno($parameterdesc_start_lines{$parameter_name}); - print "``" . $parameter . "``\n"; + print $lineprefix . "``" . $parameter . "``\n"; + $lineprefix = " "; output_highlight_rst($args{'parameterdescs'}{$parameter_name}); + $lineprefix = " "; print "\n"; } print "\n"; diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index ec84fc62774e..1fb88fdceec3 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -362,7 +362,6 @@ sub give_debian_hints() { my %map = ( "python-sphinx" => "python3-sphinx", - "sphinx_rtd_theme" => "python3-sphinx-rtd-theme", "ensurepip" => "python3-venv", "virtualenv" => "virtualenv", "dot" => "graphviz", @@ -397,7 +396,6 @@ sub give_redhat_hints() { my %map = ( "python-sphinx" => "python3-sphinx", - "sphinx_rtd_theme" => "python3-sphinx_rtd_theme", "virtualenv" => "python3-virtualenv", "dot" => "graphviz", "convert" => "ImageMagick", @@ -475,7 +473,6 @@ sub give_opensuse_hints() { my %map = ( "python-sphinx" => "python3-sphinx", - "sphinx_rtd_theme" => "python3-sphinx_rtd_theme", "virtualenv" => "python3-virtualenv", "dot" => "graphviz", "convert" => "ImageMagick", @@ -523,7 +520,6 @@ sub give_mageia_hints() { my %map = ( "python-sphinx" => "python3-sphinx", - "sphinx_rtd_theme" => "python3-sphinx_rtd_theme", "virtualenv" => "python3-virtualenv", "dot" => "graphviz", "convert" => "ImageMagick", @@ -567,7 +563,6 @@ sub give_mageia_hints() sub give_arch_linux_hints() { my %map = ( - "sphinx_rtd_theme" => "python-sphinx_rtd_theme", "virtualenv" => "python-virtualenv", "dot" => "graphviz", "convert" => "imagemagick", @@ -598,7 +593,6 @@ sub give_arch_linux_hints() sub give_gentoo_hints() { my %map = ( - "sphinx_rtd_theme" => "dev-python/sphinx_rtd_theme", "virtualenv" => "dev-python/virtualenv", "dot" => "media-gfx/graphviz", "convert" => "media-gfx/imagemagick", @@ -895,7 +889,6 @@ sub recommend_sphinx_version($) $verbose_warn_install = 0; add_package("python-sphinx", 0); - check_python_module("sphinx_rtd_theme", 1); check_distros(); @@ -968,7 +961,6 @@ sub check_needs() check_perl_module("Pod::Usage", 0); check_program("make", 0); check_program("gcc", 0); - check_python_module("sphinx_rtd_theme", 1) if (!$virtualenv); check_program("dot", 1); check_program("convert", 1); |