sphinx-badges 0.1.0

Bootstrap-style status badges for Sphinx documentation

sphinx-badges

Bootstrap-style status badges for Sphinx documentation.

Attach coloured badges to any API element, and let readers filter a toctree by badge group with a single click.

Documentation

Installation

Directly from GitHub (latest development version):

pip install git+https://github.com/NickGeneva/sphinx-badges.git

Quick start

1. Add the extension to conf.py:

   extensions = ["sphinx_badges"]
   

2. Define grouped badges in conf.py:

   badges_group_labels = {
       "stability": "Stability",
       "area":      "Area",
   }
   
   badges_definitions = {
       "stability:stable":       {"label": "Stable",       "color": "#198754", "text_color": "#fff"},
       "stability:experimental": {"label": "Experimental", "color": "#ffc107", "text_color": "#000"},
       "area:core":              {"label": "Core",         "color": "#6f42c1", "text_color": "#fff"},
       "area:utils":             {"label": "Utils",        "color": "#fd7e14", "text_color": "#fff"},
   }
   

   Badge IDs use a group:name format. badges_group_labels maps group keys to the display labels shown above each row of filter buttons. Ungrouped IDs (no colon) are also supported for simpler setups.

3. Attach badges to a page:

   my_function
   ===========
   
   .. badges:: stability:stable area:core
   
   Description here.  Also inline: :badge:`stability:stable`.
   

4. Filter a toctree by badge group:

   .. badge-filter:: stability:stable stability:experimental area:core area:utils
      :filter-mode: or
   
      .. toctree::
   
         api/module_a
         api/module_b
   

   Each group renders as its own labelled row of filter buttons. filter-mode can be or (any active badge matches) or and (all active badges must match; default).

Licence

MIT