* [PATCH 0/6] Some Sphinx improvements
@ 2021-10-08 22:06 marcandre.lureau
2021-10-08 22:06 ` [PATCH 1/6] docs/sphinx: add loaded modules to generated depfile marcandre.lureau
` (5 more replies)
0 siblings, 6 replies; 8+ messages in thread
From: marcandre.lureau @ 2021-10-08 22:06 UTC (permalink / raw)
To: qemu-devel; +Cc: pbonzini, Marc-André Lureau, Peter Maydell
From: Marc-André Lureau <marcandre.lureau@redhat.com>
Hi,
I have collected a few Sphinx-related improvements to improve depfile generation
and add some keyboard navigation. Hope you'll like it.
Marc-André Lureau (6):
docs/sphinx: add loaded modules to generated depfile
docs/sphinx: add static files to generated depfile
docs/sphinx: add templates files to generated depfile
meson: remove explicit extensions dependency file list
docs/sphinx: set navigation_with_keys=True
docs/sphinx: add 's' keyboard binding to focus search
docs/conf.py | 7 ++++++-
docs/meson.build | 10 ----------
docs/sphinx-static/custom.js | 9 +++++++++
docs/sphinx/depfile.py | 19 +++++++++++++++++--
tests/qapi-schema/meson.build | 5 ++++-
5 files changed, 36 insertions(+), 14 deletions(-)
create mode 100644 docs/sphinx-static/custom.js
--
2.33.0.721.g106298f7f9
^ permalink raw reply [flat|nested] 8+ messages in thread
* [PATCH 1/6] docs/sphinx: add loaded modules to generated depfile
2021-10-08 22:06 [PATCH 0/6] Some Sphinx improvements marcandre.lureau
@ 2021-10-08 22:06 ` marcandre.lureau
2021-10-08 22:06 ` [PATCH 2/6] docs/sphinx: add static files " marcandre.lureau
` (4 subsequent siblings)
5 siblings, 0 replies; 8+ messages in thread
From: marcandre.lureau @ 2021-10-08 22:06 UTC (permalink / raw)
To: qemu-devel; +Cc: pbonzini, Marc-André Lureau, Peter Maydell
From: Marc-André Lureau <marcandre.lureau@redhat.com>
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
docs/sphinx/depfile.py | 14 ++++++++++++--
1 file changed, 12 insertions(+), 2 deletions(-)
diff --git a/docs/sphinx/depfile.py b/docs/sphinx/depfile.py
index 277fdf0f56..b6fb926df1 100644
--- a/docs/sphinx/depfile.py
+++ b/docs/sphinx/depfile.py
@@ -12,6 +12,7 @@
import os
import sphinx
+import sys
__version__ = '1.0'
@@ -20,8 +21,17 @@ def get_infiles(env):
yield env.doc2path(x)
yield from ((os.path.join(env.srcdir, dep)
for dep in env.dependencies[x]))
+ for mod in sys.modules.values():
+ if hasattr(mod, '__file__'):
+ if mod.__file__:
+ yield mod.__file__
-def write_depfile(app, env):
+
+def write_depfile(app, exception):
+ if exception:
+ return
+
+ env = app.env
if not env.config.depfile:
return
@@ -42,7 +52,7 @@ def write_depfile(app, env):
def setup(app):
app.add_config_value('depfile', None, 'env')
app.add_config_value('depfile_stamp', None, 'env')
- app.connect('env-updated', write_depfile)
+ app.connect('build-finished', write_depfile)
return dict(
version = __version__,
--
2.33.0.721.g106298f7f9
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 2/6] docs/sphinx: add static files to generated depfile
2021-10-08 22:06 [PATCH 0/6] Some Sphinx improvements marcandre.lureau
2021-10-08 22:06 ` [PATCH 1/6] docs/sphinx: add loaded modules to generated depfile marcandre.lureau
@ 2021-10-08 22:06 ` marcandre.lureau
2021-10-08 22:06 ` [PATCH 3/6] docs/sphinx: add templates " marcandre.lureau
` (3 subsequent siblings)
5 siblings, 0 replies; 8+ messages in thread
From: marcandre.lureau @ 2021-10-08 22:06 UTC (permalink / raw)
To: qemu-devel; +Cc: pbonzini, Marc-André Lureau, Peter Maydell
From: Marc-André Lureau <marcandre.lureau@redhat.com>
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
docs/sphinx/depfile.py | 5 +++++
1 file changed, 5 insertions(+)
diff --git a/docs/sphinx/depfile.py b/docs/sphinx/depfile.py
index b6fb926df1..99539adb48 100644
--- a/docs/sphinx/depfile.py
+++ b/docs/sphinx/depfile.py
@@ -13,6 +13,7 @@
import os
import sphinx
import sys
+from pathlib import Path
__version__ = '1.0'
@@ -25,6 +26,10 @@ def get_infiles(env):
if hasattr(mod, '__file__'):
if mod.__file__:
yield mod.__file__
+ # this is perhaps going to include unused files:
+ for static_path in env.config.html_static_path:
+ for path in Path(static_path).rglob('*'):
+ yield str(path)
def write_depfile(app, exception):
--
2.33.0.721.g106298f7f9
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 3/6] docs/sphinx: add templates files to generated depfile
2021-10-08 22:06 [PATCH 0/6] Some Sphinx improvements marcandre.lureau
2021-10-08 22:06 ` [PATCH 1/6] docs/sphinx: add loaded modules to generated depfile marcandre.lureau
2021-10-08 22:06 ` [PATCH 2/6] docs/sphinx: add static files " marcandre.lureau
@ 2021-10-08 22:06 ` marcandre.lureau
2021-10-08 22:06 ` [PATCH 4/6] meson: remove explicit extensions dependency file list marcandre.lureau
` (2 subsequent siblings)
5 siblings, 0 replies; 8+ messages in thread
From: marcandre.lureau @ 2021-10-08 22:06 UTC (permalink / raw)
To: qemu-devel; +Cc: pbonzini, Marc-André Lureau, Peter Maydell
From: Marc-André Lureau <marcandre.lureau@redhat.com>
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
docs/conf.py | 2 +-
docs/sphinx/depfile.py | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/conf.py b/docs/conf.py
index ff6e92c6e2..edc2bf8fcb 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -74,7 +74,7 @@
extensions = ['kerneldoc', 'qmp_lexer', 'hxtool', 'depfile', 'qapidoc']
# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = [os.path.join(qemu_docdir, '_templates')]
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
diff --git a/docs/sphinx/depfile.py b/docs/sphinx/depfile.py
index 99539adb48..afdcbcec6e 100644
--- a/docs/sphinx/depfile.py
+++ b/docs/sphinx/depfile.py
@@ -27,7 +27,7 @@ def get_infiles(env):
if mod.__file__:
yield mod.__file__
# this is perhaps going to include unused files:
- for static_path in env.config.html_static_path:
+ for static_path in env.config.html_static_path + env.config.templates_path:
for path in Path(static_path).rglob('*'):
yield str(path)
--
2.33.0.721.g106298f7f9
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 4/6] meson: remove explicit extensions dependency file list
2021-10-08 22:06 [PATCH 0/6] Some Sphinx improvements marcandre.lureau
` (2 preceding siblings ...)
2021-10-08 22:06 ` [PATCH 3/6] docs/sphinx: add templates " marcandre.lureau
@ 2021-10-08 22:06 ` marcandre.lureau
2021-10-09 8:52 ` Marc-André Lureau
2021-10-08 22:06 ` [PATCH 5/6] docs/sphinx: set navigation_with_keys=True marcandre.lureau
2021-10-08 22:06 ` [PATCH 6/6] docs/sphinx: add 's' keyboard binding to focus search marcandre.lureau
5 siblings, 1 reply; 8+ messages in thread
From: marcandre.lureau @ 2021-10-08 22:06 UTC (permalink / raw)
To: qemu-devel; +Cc: pbonzini, Marc-André Lureau, Peter Maydell
From: Marc-André Lureau <marcandre.lureau@redhat.com>
This is now generated automatically by depfile.py.
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
docs/meson.build | 10 ----------
tests/qapi-schema/meson.build | 5 ++++-
2 files changed, 4 insertions(+), 11 deletions(-)
diff --git a/docs/meson.build b/docs/meson.build
index be4dc30f39..6177c967ff 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -37,15 +37,6 @@ endif
if build_docs
SPHINX_ARGS += ['-Dversion=' + meson.project_version(), '-Drelease=' + config_host['PKGVERSION']]
- sphinx_extn_depends = [ meson.current_source_dir() / 'sphinx/depfile.py',
- meson.current_source_dir() / 'sphinx/hxtool.py',
- meson.current_source_dir() / 'sphinx/kerneldoc.py',
- meson.current_source_dir() / 'sphinx/kernellog.py',
- meson.current_source_dir() / 'sphinx/qapidoc.py',
- meson.current_source_dir() / 'sphinx/qmp_lexer.py',
- qapi_gen_depends ]
- sphinx_template_files = [ meson.project_source_root() / 'docs/_templates/footer.html' ]
-
have_ga = have_tools and config_host.has_key('CONFIG_GUEST_AGENT')
man_pages = {
@@ -77,7 +68,6 @@ if build_docs
output: 'docs.stamp',
input: files('conf.py'),
depfile: 'docs.d',
- depend_files: [ sphinx_extn_depends, sphinx_template_files ],
command: [SPHINX_ARGS, '-Ddepfile=@DEPFILE@',
'-Ddepfile_stamp=@OUTPUT0@',
'-b', 'html', '-d', private_dir,
diff --git a/tests/qapi-schema/meson.build b/tests/qapi-schema/meson.build
index df5acfd08b..a5eae6253f 100644
--- a/tests/qapi-schema/meson.build
+++ b/tests/qapi-schema/meson.build
@@ -241,7 +241,8 @@ if build_docs
output: ['doc-good.txt'],
input: files('doc-good.json', 'doc-good.rst'),
build_by_default: true,
- depend_files: sphinx_extn_depends,
+ output: 'docs.stamp',
+ depfile: 'docs.d',
# We use -E to suppress Sphinx's caching, because
# we want it to always really run the QAPI doc
# generation code. It also means we don't
@@ -250,6 +251,8 @@ if build_docs
'-b', 'text', '-E',
'-c', meson.project_source_root() / 'docs',
'-D', 'master_doc=doc-good',
+ '-Ddepfile=@DEPFILE@',
+ '-Ddepfile_stamp=@OUTPUT0@',
meson.current_source_dir(),
meson.current_build_dir()])
--
2.33.0.721.g106298f7f9
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 5/6] docs/sphinx: set navigation_with_keys=True
2021-10-08 22:06 [PATCH 0/6] Some Sphinx improvements marcandre.lureau
` (3 preceding siblings ...)
2021-10-08 22:06 ` [PATCH 4/6] meson: remove explicit extensions dependency file list marcandre.lureau
@ 2021-10-08 22:06 ` marcandre.lureau
2021-10-08 22:06 ` [PATCH 6/6] docs/sphinx: add 's' keyboard binding to focus search marcandre.lureau
5 siblings, 0 replies; 8+ messages in thread
From: marcandre.lureau @ 2021-10-08 22:06 UTC (permalink / raw)
To: qemu-devel; +Cc: pbonzini, Marc-André Lureau, Peter Maydell
From: Marc-André Lureau <marcandre.lureau@redhat.com>
Allow navigating to the previous/next page using the keyboard's left and
right arrows. I wish this would be the default, and that the themes
would provide more key navigation, but that doesn't seem on the roadmap.
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
docs/conf.py | 1 +
1 file changed, 1 insertion(+)
diff --git a/docs/conf.py b/docs/conf.py
index edc2bf8fcb..f536483bc3 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -166,6 +166,7 @@
if LooseVersion(sphinx_rtd_theme.__version__) >= LooseVersion("0.4.3"):
html_theme_options = {
"style_nav_header_background": "#802400",
+ "navigation_with_keys": True,
}
html_logo = os.path.join(qemu_docdir, "../ui/icons/qemu_128x128.png")
--
2.33.0.721.g106298f7f9
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 6/6] docs/sphinx: add 's' keyboard binding to focus search
2021-10-08 22:06 [PATCH 0/6] Some Sphinx improvements marcandre.lureau
` (4 preceding siblings ...)
2021-10-08 22:06 ` [PATCH 5/6] docs/sphinx: set navigation_with_keys=True marcandre.lureau
@ 2021-10-08 22:06 ` marcandre.lureau
5 siblings, 0 replies; 8+ messages in thread
From: marcandre.lureau @ 2021-10-08 22:06 UTC (permalink / raw)
To: qemu-devel; +Cc: pbonzini, Marc-André Lureau, Peter Maydell
From: Marc-André Lureau <marcandre.lureau@redhat.com>
This is pretty ubiquitous. ('/' is already taken by some browsers for
quick search)
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
docs/conf.py | 4 ++++
docs/sphinx-static/custom.js | 9 +++++++++
2 files changed, 13 insertions(+)
create mode 100644 docs/sphinx-static/custom.js
diff --git a/docs/conf.py b/docs/conf.py
index f536483bc3..3161b8b127 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -182,6 +182,10 @@
'theme_overrides.css',
]
+html_js_files = [
+ 'custom.js',
+]
+
html_context = {
"display_gitlab": True,
"gitlab_user": "qemu-project",
diff --git a/docs/sphinx-static/custom.js b/docs/sphinx-static/custom.js
new file mode 100644
index 0000000000..7630654a58
--- /dev/null
+++ b/docs/sphinx-static/custom.js
@@ -0,0 +1,9 @@
+document.addEventListener('keydown', (event) => {
+ // find a better way to look it up?
+ let search_input = document.getElementsByName('q')[0];
+
+ if (event.code === 'KeyS' && document.activeElement !== search_input) {
+ event.preventDefault();
+ search_input.focus();
+ }
+});
--
2.33.0.721.g106298f7f9
^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [PATCH 4/6] meson: remove explicit extensions dependency file list
2021-10-08 22:06 ` [PATCH 4/6] meson: remove explicit extensions dependency file list marcandre.lureau
@ 2021-10-09 8:52 ` Marc-André Lureau
0 siblings, 0 replies; 8+ messages in thread
From: Marc-André Lureau @ 2021-10-09 8:52 UTC (permalink / raw)
To: QEMU; +Cc: Paolo Bonzini, Peter Maydell
[-- Attachment #1: Type: text/plain, Size: 3451 bytes --]
Hi
On Sat, Oct 9, 2021 at 2:09 AM <marcandre.lureau@redhat.com> wrote:
> From: Marc-André Lureau <marcandre.lureau@redhat.com>
>
> This is now generated automatically by depfile.py.
>
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> ---
> docs/meson.build | 10 ----------
> tests/qapi-schema/meson.build | 5 ++++-
> 2 files changed, 4 insertions(+), 11 deletions(-)
>
> diff --git a/docs/meson.build b/docs/meson.build
> index be4dc30f39..6177c967ff 100644
> --- a/docs/meson.build
> +++ b/docs/meson.build
> @@ -37,15 +37,6 @@ endif
> if build_docs
> SPHINX_ARGS += ['-Dversion=' + meson.project_version(), '-Drelease=' +
> config_host['PKGVERSION']]
>
> - sphinx_extn_depends = [ meson.current_source_dir() /
> 'sphinx/depfile.py',
> - meson.current_source_dir() / 'sphinx/hxtool.py',
> - meson.current_source_dir() /
> 'sphinx/kerneldoc.py',
> - meson.current_source_dir() /
> 'sphinx/kernellog.py',
> - meson.current_source_dir() /
> 'sphinx/qapidoc.py',
> - meson.current_source_dir() /
> 'sphinx/qmp_lexer.py',
> - qapi_gen_depends ]
> - sphinx_template_files = [ meson.project_source_root() /
> 'docs/_templates/footer.html' ]
> -
> have_ga = have_tools and config_host.has_key('CONFIG_GUEST_AGENT')
>
> man_pages = {
> @@ -77,7 +68,6 @@ if build_docs
> output: 'docs.stamp',
> input: files('conf.py'),
> depfile: 'docs.d',
> - depend_files: [ sphinx_extn_depends,
> sphinx_template_files ],
> command: [SPHINX_ARGS, '-Ddepfile=@DEPFILE@',
> '-Ddepfile_stamp=@OUTPUT0@',
> '-b', 'html', '-d', private_dir,
> diff --git a/tests/qapi-schema/meson.build b/tests/qapi-schema/meson.build
> index df5acfd08b..a5eae6253f 100644
> --- a/tests/qapi-schema/meson.build
> +++ b/tests/qapi-schema/meson.build
> @@ -241,7 +241,8 @@ if build_docs
> output: ['doc-good.txt'],
> input: files('doc-good.json',
> 'doc-good.rst'),
> build_by_default: true,
> - depend_files: sphinx_extn_depends,
> + output: 'docs.stamp',
>
This line should be removed (it breaks the test)
+ depfile: 'docs.d',
> # We use -E to suppress Sphinx's caching,
> because
> # we want it to always really run the QAPI
> doc
> # generation code. It also means we don't
> @@ -250,6 +251,8 @@ if build_docs
> '-b', 'text', '-E',
> '-c',
> meson.project_source_root() / 'docs',
> '-D', 'master_doc=doc-good',
> + '-Ddepfile=@DEPFILE@',
> + '-Ddepfile_stamp=@OUTPUT0@',
> meson.current_source_dir(),
> meson.current_build_dir()])
>
> --
> 2.33.0.721.g106298f7f9
>
>
>
--
Marc-André Lureau
[-- Attachment #2: Type: text/html, Size: 4970 bytes --]
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2021-10-09 8:55 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-10-08 22:06 [PATCH 0/6] Some Sphinx improvements marcandre.lureau
2021-10-08 22:06 ` [PATCH 1/6] docs/sphinx: add loaded modules to generated depfile marcandre.lureau
2021-10-08 22:06 ` [PATCH 2/6] docs/sphinx: add static files " marcandre.lureau
2021-10-08 22:06 ` [PATCH 3/6] docs/sphinx: add templates " marcandre.lureau
2021-10-08 22:06 ` [PATCH 4/6] meson: remove explicit extensions dependency file list marcandre.lureau
2021-10-09 8:52 ` Marc-André Lureau
2021-10-08 22:06 ` [PATCH 5/6] docs/sphinx: set navigation_with_keys=True marcandre.lureau
2021-10-08 22:06 ` [PATCH 6/6] docs/sphinx: add 's' keyboard binding to focus search marcandre.lureau
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.