Quickstart#

This section contains basic information about sphinx-btn to get you started.

Installation#

Use pip to install sphinx-btn in your environment:

pip install sphinx-btn

Extension setup#

After installing sphinx-btn, add sphinxcontrib.icon and sphinxcontrib.btn to the list of extensions in your conf.py file:

extensions = [
    #[...]
    "sphinxcontrib.icon",
    "sphinxcontrib.btn"
]

Note

The sphinx-btn extention rely on sphinx-icon to provide access to the fontawesome 6.3.0 icons font/metadata.

Icon directive#

You can now add buttons directly in your documentation:

I'm a :btn:`<fa-solid fa-folder> fa-folder` btn.
I'm a :btn:`<fa-solid fa-folder>` btn.
I'm a :btn:`fa-folder` btn.

I’m a fa-folder btn.

I’m a btn.

I’m a fa-folder btn.

Note

Support is provided for older version of Fontawesome. Documentation using fas|far|fab or fa will continue working. Be aware that the icon you want to use may changed name since then.

HTML output#

In the HTML output, the CSS and JS from Fontawesome 6.3.0 are added to the output in the <head> tag.

<link rel="stylesheet" type="text/css" href="<webpath>/build/html/_font/fontawesome/css/all.min.css">
<!-- -->
<script src="<webpath>/build/html/_font/fontawesome/css/all.min.js">

Then for each btn role occurence an <span> of class guilabel tag will be used:

<span class="guilabel">
    <i class="fa-solid fa-folder"></i>
    <span style="margin-left: .5em;">fa-folder</span>
</span>

Latex output#

For the latex output, the sphinx-btn extention need to use the webfonts provided by fontawesome. It will thus force the use of the XeLaTex builder to allow use of the fontspec and tcolorbox packages. Then 3 new font will be added to the preamble of the tex file as well as a sphinxbtn command:

\newfontfamily{\solid}{fa-solid-900.ttf}
\newfontfamily{\regular}{fa-regular-400.ttf}
\newfontfamily{\brands}{fa-brands-400.ttf}

\newtcbox{\sphinxbtn}[1][]{box align=base, nobeforeafter, size=small, boxsep=2pt, #1}

Then for each btn role occurence the following command will be used:

\sphinxbtn{{\solid\symbol{"F07B}} fa-folder}

where solid is the font style selected in the role and F007 being the unicode of the selected icon.