[PATCH 0/6] Some Sphinx improvements

[PATCH 0/6] Some Sphinx improvements

[marcandre.lureau]

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

[PATCH 1/6] docs/sphinx: add loaded modules to generated depfile

[marcandre.lureau]

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

[PATCH 2/6] docs/sphinx: add static files to generated depfile

[marcandre.lureau]

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

[PATCH 3/6] docs/sphinx: add templates files to generated depfile

[marcandre.lureau]

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

[PATCH 4/6] meson: remove explicit extensions dependency file list

[marcandre.lureau]

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

[PATCH 5/6] docs/sphinx: set navigation_with_keys=True

[marcandre.lureau]

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

[PATCH 6/6] docs/sphinx: add 's' keyboard binding to focus search

[marcandre.lureau]

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

Re: [PATCH 4/6] meson: remove explicit extensions dependency file list

[Marc-André Lureau]

[-- 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 --]