rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-06-02 06:23:52 +08:00
Code Issues Packages Projects Releases Wiki Activity

build: Fix indexing so it works on HTML and PDF.

Browse Source 
- Remove all genindex.rst files, these are generated and should not
  exist in our source.
- Fix the HTML templates so the local specialisation works.
- Add a index link to the sidebar for HTML.

Note, there is no TOC entry for the index in the PDF output and I
cannot figure out how to add one.

Closes #3503
This commit is contained in:
Chris Johns 2018-08-21 13:41:51 +10:00
parent 9bfda06298
commit 5ce8e43506
30 changed files with 71 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
bsp-howto/genindex.rst
View File

@ -1,4 +0,0 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
Index
=====

2
bsp-howto/index.rst
View File

@ -61,4 +61,4 @@ to the Community Project hosted at http://www.rtems.org/.
ide_controller ide_controller
command command
genindex * :ref:`genindex`

4
c-user/genindex.rst
View File

@ -1,4 +0,0 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
Index
=====

2
c-user/index.rst
View File

@ -83,4 +83,4 @@ to the Community Project hosted at http://www.rtems.org/.
glossary glossary
zreferences zreferences
genindex * :ref:`genindex`

11
common/_templates/layout.html
View File

@ -1,5 +1,12 @@
{# Import the theme's layout. #} {# Import the theme's layout. #}
{% extends "!layout.html" %} {% extends "!layout.html" %}
{% block sidebartitle %}
<a href="https://docs.rtems.org/">RTEMS Documentation Project</a>
{{ super() }}
{% endblock %}
{% block menu %}
{{ super() }}
<a class="reference internal" href="genindex.html">Index</a>
{% endblock %}
{# Custom CSS overrides #} {# Custom CSS overrides #}
{% set bootswatch_css_custom = ['_static/my-styles.css'] %} {% set css_files = ['_static/my-styles.css'] %}

6
common/conf.py
View File

@ -34,7 +34,7 @@ extensions = [
] ]
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.
templates_path = ['build/_templates'] #templates_path = ['build/_templates']
# The suffix of source filenames. # The suffix of source filenames.
source_suffix = '.rst' source_suffix = '.rst'
@ -202,7 +202,9 @@ latex_elements = {
'preamble': r''' 'preamble': r'''
\newcommand{\rtemscopyright}{%s} \newcommand{\rtemscopyright}{%s}
\usepackage{rtemsstyle} \usepackage{rtemsstyle}
''' % (copyright) ''' % (copyright),
'printindex': r'\footnotesize\raggedright\printindex',
'parsedliteralwraps': True,
} }

4
common/rtemsstyle.sty
View File

@ -10,10 +10,6 @@
\renewenvironment{tabulary}{\underscoresplit\oldtabulary}{\endoldtabulary\endunderscoresplit} \renewenvironment{tabulary}{\underscoresplit\oldtabulary}{\endoldtabulary\endunderscoresplit}
\let\oldprintindex\printindex
\renewenvironment{printindex}{\underscoresplit\oldprintindex}
\usepackage{minted} \usepackage{minted}
\fvset{ \fvset{
breaklines=true, breaklines=true,

3
common/sphinx_rtd_theme_rtems/layout.html
View File

@ -7,9 +7,6 @@
{%- set titlesuffix = "" %} {%- set titlesuffix = "" %}
{%- endif %} {%- endif %}
{# Custom CSS overrides #}
{% set extra_css_files = ['_static/my-styles.css'] %}
<!DOCTYPE html> <!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]--> <!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]--> <!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->

76
common/waf.py
View File

@ -1,4 +1,16 @@
import sys, os, re #
# RTEMS Documentation Project
#
# Waf build support.
#
from __future__ import print_function
import os
import re
import sys
from waflib.Build import BuildContext from waflib.Build import BuildContext
import latex import latex
@ -24,10 +36,14 @@ def build_date():
def version_cmdline(ctx): def version_cmdline(ctx):
return '-Drelease="%s" -Dversion="%s"' % (ctx.env.VERSION, ctx.env.VERSION) return '-Drelease="%s" -Dversion="%s"' % (ctx.env.VERSION, ctx.env.VERSION)
def sphinx_cmdline(ctx, build_type, conf_dir, doctrees, source_dir, output_dir): def sphinx_cmdline(ctx, build_type, conf_dir, doctrees,
rule = "${BIN_SPHINX_BUILD} %s -b %s -c %s %s -d %s %s %s ${SRC}" % \ source_dir, output_dir, configs = []):
cfgs = ''
for c in configs:
cfgs += ' -D %s=%s' % (c, configs[c])
rule = "${BIN_SPHINX_BUILD} %s -b %s -c %s %s -d %s %s %s %s ${SRC}" % \
(sphinx_verbose(ctx), build_type, conf_dir, version_cmdline(ctx), (sphinx_verbose(ctx), build_type, conf_dir, version_cmdline(ctx),
doctrees, source_dir, output_dir) doctrees, cfgs, source_dir, output_dir)
return rule return rule
def cmd_spell(ctx): def cmd_spell(ctx):
@ -140,43 +156,35 @@ def pdf_resources(ctx, buildtype):
fnode = ctx.path.get_bld().make_node(buildtype) fnode = ctx.path.get_bld().make_node(buildtype)
fnode.mkdir() fnode.mkdir()
local_packages = latex.local_packages() local_packages = latex.local_packages()
targets = []
if local_packages is not None: if local_packages is not None:
srcs = [os.path.join(base, p) for p in local_packages] srcs = [os.path.join(base, p) for p in local_packages]
ctx( targets += [fnode.make_node(p) for p in local_packages]
features = "subst", ctx(features = "subst",
is_copy = True, is_copy = True,
source = srcs, source = srcs,
target = [fnode.make_node(p) for p in local_packages] target = targets)
) targets += [fnode.make_node('rtemsextrafonts.sty')]
ctx( ctx(features = "subst",
features = "subst",
is_copy = True, is_copy = True,
source = os.path.join(base, ctx.env.RTEMSEXTRAFONTS), source = os.path.join(base, ctx.env.RTEMSEXTRAFONTS),
target = fnode.make_node('rtemsextrafonts.sty') target = fnode.make_node('rtemsextrafonts.sty'))
) return targets
def html_resources(ctx, buildtype): def html_resources(ctx, buildtype):
extra_source = []
for dir_name in ["_static", "_templates"]: for dir_name in ["_static", "_templates"]:
files = ctx.path.parent.find_node("common").ant_glob("%s/*" % dir_name) files = ctx.path.parent.find_node("common").ant_glob("%s/*" % dir_name)
fnode = ctx.path.get_bld().make_node(os.path.join(buildtype, dir_name)) fnode = ctx.path.get_bld().make_node(os.path.join(buildtype, dir_name))
targets = [fnode.make_node(x.name) for x in files]
extra_source += targets
fnode.mkdir() # dirs fnode.mkdir() # dirs
ctx( ctx(features = "subst",
features = "subst",
is_copy = True, is_copy = True,
source = files, source = files,
target = [fnode.make_node(x.name) for x in files] target = targets)
) ctx.add_group()
return extra_source
# copy images
# ctx.path.get_bld().make_node("images").mkdir()
# files = ctx.path.parent.ant_glob("images/**")
# ctx(
# features = "subst",
# is_copy = True,
# source = files,
# target = [x.srcpath().replace("../", "") for x in files]
# )
def check_sphinx_extension(ctx, extension): def check_sphinx_extension(ctx, extension):
def run_sphinx(bld): def run_sphinx(bld):
@ -196,7 +204,6 @@ def check_sphinx_extension(ctx, extension):
ctx.fatal('The configuration failed') ctx.fatal('The configuration failed')
ctx.end_msg('found') ctx.end_msg('found')
def cmd_configure(ctx): def cmd_configure(ctx):
check_sphinx = not ctx.env.BIN_SPHINX_BUILD check_sphinx = not ctx.env.BIN_SPHINX_BUILD
if check_sphinx: if check_sphinx:
@ -256,12 +263,13 @@ def cmd_configure(ctx):
def doc_pdf(ctx, source_dir, conf_dir, extra_source): def doc_pdf(ctx, source_dir, conf_dir, extra_source):
buildtype = 'latex' buildtype = 'latex'
build_dir, output_node, output_dir, doctrees = build_dir_setup(ctx, buildtype) build_dir, output_node, output_dir, doctrees = build_dir_setup(ctx, buildtype)
pdf_resources(ctx, buildtype) resources = pdf_resources(ctx, buildtype)
rule = sphinx_cmdline(ctx, buildtype, conf_dir, doctrees, source_dir, output_dir) rule = sphinx_cmdline(ctx, buildtype, conf_dir, doctrees, source_dir, output_dir)
ctx( ctx(
rule = rule, rule = rule,
cwd = ctx.path, cwd = ctx.path,
source = ctx.path.ant_glob('**/*.rst') + extra_source, source = ctx.path.ant_glob('**/*.rst') + extra_source,
depends_on = extra_source,
target = ctx.path.find_or_declare("%s/%s.tex" % (buildtype, target = ctx.path.find_or_declare("%s/%s.tex" % (buildtype,
ctx.path.name)) ctx.path.name))
) )
@ -306,12 +314,13 @@ def doc_singlehtml(ctx, source_dir, conf_dir, extra_source):
buildtype = 'singlehtml' buildtype = 'singlehtml'
build_dir, output_node, output_dir, doctrees = build_dir_setup(ctx, buildtype) build_dir, output_node, output_dir, doctrees = build_dir_setup(ctx, buildtype)
html_resources(ctx, buildtype) resource = html_resources(ctx, buildtype)
rule = sphinx_cmdline(ctx, buildtype, conf_dir, doctrees, source_dir, output_dir) rule = sphinx_cmdline(ctx, buildtype, conf_dir, doctrees, source_dir, output_dir)
ctx( ctx(
rule = rule, rule = rule,
cwd = ctx.path, cwd = ctx.path,
source = ctx.path.ant_glob('**/*.rst') + extra_source, source = ctx.path.ant_glob('**/*.rst') + extra_source,
depends_on = resources,
target = ctx.path.find_or_declare("%s/index.html" % (buildtype)), target = ctx.path.find_or_declare("%s/index.html" % (buildtype)),
install_path = None install_path = None
) )
@ -326,12 +335,15 @@ def doc_singlehtml(ctx, source_dir, conf_dir, extra_source):
def doc_html(ctx, source_dir, conf_dir, extra_source): def doc_html(ctx, source_dir, conf_dir, extra_source):
buildtype = 'html' buildtype = 'html'
build_dir, output_node, output_dir, doctrees = build_dir_setup(ctx, buildtype) build_dir, output_node, output_dir, doctrees = build_dir_setup(ctx, buildtype)
html_resources(ctx, buildtype) resources = html_resources(ctx, buildtype)
rule = sphinx_cmdline(ctx, buildtype, conf_dir, doctrees, source_dir, output_dir) templates = os.path.join(str(ctx.path.get_bld()), buildtype, '_templates')
configs = { 'templates_path': templates }
rule = sphinx_cmdline(ctx, buildtype, conf_dir, doctrees, source_dir, output_dir, configs)
ctx( ctx(
rule = rule, rule = rule,
cwd = ctx.path, cwd = ctx.path,
source = ctx.path.ant_glob('**/*.rst') + extra_source, source = ctx.path.ant_glob('**/*.rst') + extra_source,
depends_on = resources,
target = ctx.path.find_or_declare('%s/index.html' % buildtype), target = ctx.path.find_or_declare('%s/index.html' % buildtype),
install_path = None install_path = None
) )

2
cpu-supplement/index.rst
View File

@ -61,3 +61,5 @@ to the Community Project hosted at http://www.rtems.org/.
sparc sparc
sparc64 sparc64
zreferences zreferences
* :ref:`genindex`

4
develenv/genindex.rst
View File

@ -1,4 +0,0 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
Index
=====

2
develenv/index.rst
View File

@ -47,4 +47,4 @@ to the Community Project hosted at http://www.rtems.org/.
utilities utilities
command command
genindex * :ref:`genindex`

4
eclipse/genindex.rst
View File

@ -1,4 +0,0 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
Index
=====

2
eclipse/index.rst
View File

@ -50,4 +50,4 @@ to the Community Project hosted at http://www.rtems.org/.
glossary glossary
genindex * :ref:`genindex`

4
filesystem/genindex.rst
View File

@ -1,4 +0,0 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
Index
=====

2
filesystem/index.rst
View File

@ -52,4 +52,4 @@ to the Community Project hosted at http://www.rtems.org/.
trivial_ftp trivial_ftp
command_and_variable command_and_variable
genindex * :ref:`genindex`

4
networking/genindex.rst
View File

@ -1,4 +0,0 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
Index
=====

2
networking/index.rst
View File

@ -52,4 +52,4 @@ to the Community Project hosted at http://www.rtems.org/.
dec_21140 dec_21140
command command
genindex * :ref:`genindex`

4
porting/genindex.rst
View File

@ -1,4 +0,0 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
Index
=====

2
porting/index.rst
View File

@ -54,4 +54,4 @@ to the Community Project hosted at http://www.rtems.org/.
miscellanous miscellanous
command command
genindex * :ref:`genindex`

4
posix-compliance/genindex.rst
View File

@ -1,4 +0,0 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
Index
=====

2
posix-compliance/index.rst
View File

@ -48,4 +48,4 @@ to the Community Project hosted at http://www.rtems.org/.
glossary glossary
zreferences zreferences
genindex * :ref:`genindex`

4
posix-users/genindex.rst
View File

@ -1,4 +0,0 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
Index
=====

2
posix-users/index.rst
View File

@ -67,4 +67,4 @@ to the Community Project hosted at http://www.rtems.org/.
status_of_implementation status_of_implementation
command command
genindex * :ref:`genindex`

4
rsb/genindex.rst
View File

@ -1,4 +0,0 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
Index
=====

2
rsb/index.rst
View File

@ -62,4 +62,4 @@ Table of Contents
commands commands
bug-reporting bug-reporting
genindex * :ref:`genindex`

4
shell/genindex.rst
View File

@ -1,4 +0,0 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
Index
=====

2
shell/index.rst
View File

@ -55,4 +55,4 @@ to the Community Project hosted at http://www.rtems.org/.
function_and_variable function_and_variable
concept concept
genindex * :ref:`genindex`

4
user/genindex.rst
View File

@ -1,4 +0,0 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
Index
=====

2
user/index.rst
View File

@ -59,4 +59,4 @@ to the Community Project hosted at http://www.rtems.org/.
glossary/index glossary/index
genindex * :ref:`genindex`