Sphinx - Add custom field / variable to be used in HTML Template

Question

I am trying to extract meta information from .rst files to be included in the HTML Template. I assumed that if I put something like

.. :newVariable: My Text

into a .rst file and then build the HTML using my own template, I would be able to include newVariable in the HTML Header. But it doesn't work. I tried a couple of things with no avail.

Is this solvable without modifying Sphinx sources?

Answer 1

In your .rst file, put at the top a field list with the variable name and value you'd like to pass. The meta information is not required, but shown so you can see where to put your code.

.. meta::
   :author: My Company, Inc.
   :description: Introduction to ...
   :copyright: Copyright © 2014 My Company, Inc.

:my-variable: my variable's value

.. _introduction:

==================================================
Introduction to ....
==================================================

In your template, you can now access my-variable using code such as:

{%- set my-variable = '' %}
{%- set my-variable_key = 'my-variable' %}
{%- if meta is defined %}
    {%- if my-variable_key in meta.viewkeys() %}
        {%- set my-variable = meta.get(my-variable_key) %}
    {%- endif %}
{%- endif %}

You can now use my-variable and its value.

Note that in the template, meta refers to the second field list; metatags refers to the docutils-generated HTML for the header meta-tags, built from the .. meta::. They are two different objects, with the same name...

Answer 2

I'm not sure this exactly answers your question, but there is a dictionary called html_context you can place in your sphinx configuration file (conf.py) that allows you to define custom variables that you can then render in your html templates. You can check the docs here: http://sphinx-doc.org/config.html#confval-html_context

In my application, I had a list of sofware release dates that I wanted to render in my index.html doc splash page. I set it up like this:

In releases.py:

RELEASES = [                                                               
   ( "Jun 05, 2014", "095", "" ),                                                
   ( "May 28, 2014", "094", "" ),                                                
   ( "Apr 29, 2014", "093", "" ),
   ...
]

In conf.py:

# Get list of releases for index page rendering                            
import releases                                    
html_context = {                                                                 
    'releases' : releases.RELEASES,                                   
}  

In index.html:

 {%- for release in releases %}                                         
   <p><span class="style4"><em><strong>{{ release[0] }} ... {{ release[1] }} was released ... </p>
 {%- endfor %}