From d5389d3145ef0e47463f620835131557c99a331d Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Fri, 23 Sep 2022 16:28:57 -0600 Subject: [PATCH 1/6] docs: Switch the default HTML theme to alabaster The read-the-docs theme is not entirely attractive and doesn't give us control over the left column. "Alabaster" is deemed the default Sphinx theme, it is currently maintained and shipped bundled with Sphinx itself, so there is no need to install it separately. Switch over to this theme as the default for building kernel documentation; the DOCS_THEME environment variable can still be used to select a different theme. Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index b50c85083149..629f4afeb0eb 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: @@ -324,6 +342,10 @@ if html_theme == 'classic': 'bodyfont': "serif", 'headfont': "sans-serif", } +else: + html_theme_options = { + 'description': get_cline_version(), + } sys.stderr.write("Using %s theme\n" % html_theme) @@ -370,8 +392,8 @@ html_static_path = ['sphinx-static'] 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']} +# Note that the RTD theme ignores this +html_sidebars = { '**': ["about.html", 'searchbox.html', 'localtoc.html', 'sourcelink.html']} # Additional templates that should be rendered to pages, maps page names to # template names. From 2056b920c615566084cd9aa105b54b62a516161e Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 26 Sep 2022 17:48:59 -0600 Subject: [PATCH 2/6] docs: tweak some Alabaster style parameters This is just the beginning: tighten up the layout a bit to improve the information density in the browser. Also reconfigure the page width in terms of character units (em) rather than pixels, making it more display-independent. To that end, add a custom.css file to tweak Alabaster CSS settings. Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 3 +++ Documentation/sphinx-static/custom.css | 14 ++++++++++++++ 2 files changed, 17 insertions(+) create mode 100644 Documentation/sphinx-static/custom.css diff --git a/Documentation/conf.py b/Documentation/conf.py index 629f4afeb0eb..1dbf3d6a55de 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -345,6 +345,9 @@ if html_theme == 'classic': else: html_theme_options = { 'description': get_cline_version(), + 'font_size': '10pt', + 'page_width': '65em', + 'sidebar_width': '15em', } sys.stderr.write("Using %s theme\n" % html_theme) diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css new file mode 100644 index 000000000000..6b0e554cea0a --- /dev/null +++ b/Documentation/sphinx-static/custom.css @@ -0,0 +1,14 @@ +/* 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.document { margin: 20px 10px 0 10px; } +div.sphinxsidebarwrapper { padding: 1em 0.4em; } From 26d797ffc1c06f05ccc06f70977ebe386d628f14 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 27 Sep 2022 10:41:15 -0600 Subject: [PATCH 3/6] docs: update sphinx.rst to reflect the default theme change We don't default to Read The Docs anymore; update the docs to match. Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/doc-guide/sphinx.rst | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) 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 From df19817f3ff3de28e87139b6d172c0094402e1f2 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 27 Sep 2022 10:45:50 -0600 Subject: [PATCH 4/6] docs: sphinx-pre-install: don't require the RTD theme We don't default to the RTD theme anymore, so sphinx-pre-install need not insist on installing it. Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/sphinx/requirements.txt | 1 - scripts/sphinx-pre-install | 8 -------- 2 files changed, 9 deletions(-) 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/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); From eaf710ceb5ae284778a87c0d0f2348c19e3e4751 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Fri, 30 Sep 2022 11:52:09 -0600 Subject: [PATCH 5/6] docs: improve the HTML formatting of kerneldoc comments Make a few changes to cause functions documented by kerneldoc to stand out better in the rendered documentation. Specifically, change kernel-doc to put the description section into a ".. container::" section, then add a bit of CSS to indent that section relative to the function prototype (or struct or enum definition). Tweak a few other CSS parameters while in the neighborhood to improve the formatting. Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/sphinx-static/custom.css | 16 +++++++- scripts/kernel-doc | 54 ++++++++++++++++---------- 2 files changed, 48 insertions(+), 22 deletions(-) diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css index 6b0e554cea0a..9b36f7abd24f 100644 --- a/Documentation/sphinx-static/custom.css +++ b/Documentation/sphinx-static/custom.css @@ -10,5 +10,19 @@ div.body h3 { font-size: 130%; } /* Tighten up the layout slightly */ div.body { padding: 0 15px 0 10px; } -div.document { margin: 20px 10px 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/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
) 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"; From 02d33e86468c604f0e2fe9a63c312dcd1a021b13 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 11 Oct 2022 11:25:25 -0600 Subject: [PATCH 6/6] docs: decruft Documentation/conf.py Remove the ancient support for the Sphinx "classic" theme; everybody will have alabaster, so that fallback is no longer needed. While in the neighborhood: get rid of lots of useless comment lines. They describe the state of Sphinx options when we first created that file and are just clutter now. Suggested-by: Mauro Carvalho Chehab Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 181 +----------------------------------------- 1 file changed, 2 insertions(+), 179 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 1dbf3d6a55de..6ab47833ab6c 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -297,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(" ") @@ -313,36 +313,7 @@ if major <= 1 and minor < 8: for l in html_css_files: html_context['css_files'].append('_static/' + l) -if html_theme == 'classic': - 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", - } -else: +if html_theme == 'alabaster': html_theme_options = { 'description': get_cline_version(), 'font_size': '10pt', @@ -352,44 +323,11 @@ else: 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 -# " v 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 @@ -398,50 +336,6 @@ html_use_smartypants = False # Note that the RTD theme ignores this html_sidebars = { '**': ["about.html", '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 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' - # Output file base name for HTML help builder. htmlhelp_basename = 'TheLinuxKerneldoc' @@ -583,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. @@ -604,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 #