/sphinx-watermark

Sphinx extension for adding watermarks to HTML output

Primary LanguagePythonGNU General Public License v3.0GPL-3.0

Sphinx Watermark

GPL3 License Maintainability Project Status Package Version

sphinx-watermark is an extension for Sphinx that enables watermarks for HTML output.

Full documentation: https://jokneemo.github.io/sphinx-watermark

Why a Fork?

Forked from kallimachos/sphinxmark

This fork was created primarily to remove the dependency on bottle, and to support updates to Sphinx v7, Docutils, and Pillow.

Some themes perform differently in newer version of Docutils. The main issues faced are html elements are changed between div, section, article, etc.

Sphinxmark only supported div elements and the configuration changes I made to support it were too expansive for a simple pull request. See below for all of the enhancements added.

What's Different?

  • Removed bottle dependency
  • HTML element selection
  • Static png name to support spaces in text
  • Collection of fonts
  • Customizable border

Installation

Install sphinx-watermark using pip:

$ pip3 install sphinx-watermark

Usage

  1. Add sphinx-watermark to the list of extensions in conf.py:

    extensions = ['sphinx_watermark']

  2. Enable and configure sphinx-watermark in conf.py. You only have to include the values you want to change from default.

    Below is the bare-minimum config for an Internal Draft watermark:

    watermark = {
   'enabled': False,
   'text': 'Internal\nDraft'
}

    Below are the defaults for all options: (Notice that watermarks are disabled by default.)

    watermark = {
   'enabled': False,
   'selector': {
      'type': 'div',
      'class': 'body'
   },
   'position': {
      'margin': None,
      'repeat': True,
      'fixed': False
   },
   'image': None,
   'text': {
      'content': None,
      'align': 'center',
      'font': 'RubikDistressed',
      'color': (255, 0, 0),
      'opacity': 40,
      'size': 100,
      'rotation': 0,
      'width': 816,
      'spacing': 400,
      'border': {
            'outline': (255, 0, 0),
            'fill': None,
            'width': 10,
            'padding': 30,
            'radius': 20,
      }
   }
}

  3. Build your docs as normal. The defined watermark should appear behind the text.

    Note

    Some Sphinx themes place body content in different CSS divs. See the sphinx-watermark documentation for full configuration details.