obda.net

When generating HTML documentation with Sphinx, it is possible to adjust a couple of theme-related settings by defining html_theme_options in your conf.py, e.g.:

html_theme_options = {
    'rightsidebar': True,
    'textcolor': '#333',
}

However, the available options that can be customized are (a) rather restricted, and (b) specific to each theme. The [options] section of a theme’s theme.conf sheds light on what can be done (and what not).

On a global basis, though, you can define html_context to add some custom CSS and JavaScript files:

html_context = {
    'css_files': ['_static/custom.css'],
    'script_files': ['_static/custom.js'],
}

The files listed there will be included last in the generated HTML files’ sources, so it is easy to directly tweak the generated documentation’s final appearance (and, if needed, behavior).

For reference, have a look at Sphinx’s builders.html.StandaloneHTMLBuilder.prepare_writing() and see how self.globalcontext gets populated there.

Articles tagged with gentoo may not totally apply to your preferred flavor of Linux.

If you are using Microsoft’s excellent Natural Ergonomic Keyboard 4000—at least one product that Microsoft got right—under Linux, chances are that the zoom slider in the middle of the keyboard does not work out of the box. The problem is that the zoom slider uses keycodes greater than 255, which the evdev driver cannot handle.

Fortunately, you can use udev to remap the keys. The default keyboard mappings are contained in /lib/udev/hwdb.d/60-keyboard.hwdb, where you will also find detailed documentation comments on the file format in the header, including:

# To update this file, create a new file
#   /etc/udev/hwdb.d/70-keyboard.hwdb
# and add your rules there. To load the new rules execute (as root):
#   udevadm hwdb --update
#   udevadm trigger /dev/input/eventXX
# where /dev/input/eventXX is the keyboard in question. If in
# doubt, simply use /dev/input/event* to reload all input rules.

You might even already find a section for the Natural Ergonomic Keyboard 4000 in this file. If that is the case, copy its definition and use it as a starting point for the new /etc/udev/hwdb.d/70-keyboard.hwdb. If you want the zoom slider keys to be mapped as “Page Up” and “Page Down” keys, use the following:

keyboard:usb:v045Ep00DB*
 KEYBOARD_KEY_c022d=pageup
 KEYBOARD_KEY_c022e=pagedown

Of course, you can map it to anything you like. For example, to emulate a mouse wheel scroll, you could define your custom mapping as:

keyboard:usb:v045Ep00DB*
 KEYBOARD_KEY_c022d=scrollup
 KEYBOARD_KEY_c022e=scrolldown

This should result in Xorg receiving the zoom slider keys as XF86ScrollUp and XF86ScrollDown. Finally, make things work with xdotool¹ by binding those keys within your window manager to run xdotool click 4 (scroll up) and xdotool click 5 (scroll down).

Git does not support to ignore files based on the current branch. Patterns listed in any .gitignore file as well as in .git/info/exclude are always applied. A workaround is possible by creating per-branch ignore/exclude files, and automatically symlinking the correct one using Git’s post-checkout hook:

This hook is invoked when a git checkout is run after having updated the worktree. The hook is given three parameters: the ref of the previous HEAD, the ref of the new HEAD (which may or may not have changed), and a flag indicating whether the checkout was a branch checkout (changing branches, flag=1) or a file checkout (retrieving a file from the index, flag=0). This hook cannot affect the outcome of git checkout.

For example, the following script looks if there is a file named exclude.<branchname> in the .git/info directory, and uses this as link target for .git/info/exclude. If there is no branch-specific exclude file, it will symlink exclude.__default__ instead.

#!/bin/sh

old_ref=$1
new_ref=$2
branch_switched=$3

if [[ $branch_switched != '1' ]]
then
    exit 0
fi

current_branch=$(git rev-parse --abbrev-ref HEAD)
hook_dir=$(dirname $0)
info_dir=$(realpath "$hook_dir/../info")

exclude_target='__default__'
if [[ -f "$info_dir/exclude.$current_branch" ]]
then
    exclude_target=$current_branch
fi
cd $info_dir
rm exclude
ln -s exclude.$exclude_target exclude

Modify this script as needed, save it as .git/hooks/post-checkout, and make it executable—et voilà.