faculty-sphinx-theme

faculty-sphinx-theme is a Sphinx theme for Faculty projects. It's based on the Read the Docs theme, but with Faculty branding and an optional navigation bar for use in the Faculty platform docs.

Installation

pip install faculty-sphinx-theme

Usage

Install faculty-sphinx-theme and configure your Sphinx project to use the theme. In your project's conf.py, add faculty_sphinx_theme to the list of enabled extensions:

extensions = [
    "faculty_sphinx_theme",
    # Plus any other extensions you are using
]

and modify the html_theme setting to:

html_theme = "faculty-sphinx-theme"

Theme options

The theme provides an optional extra navbar with custom links. To enable it, use the faculty_navbar settings. You'll probably also want to set the faculty_navbar_root setting which defines the link on the "Faculty logo":

html_theme_options = {
    "faculty_navbar": True,
    "faculty_navbar_root": "https://docs.faculty.ai/",
}

To add entries to the navbar, add sections to the faculty_navbar_content setting:

html_theme_options = {
    "faculty_navbar": True,
    "faculty_navbar_root": "https://docs.faculty.ai/",
    "faculty_navbar_content": [
        {"title": "Section 1", "url": "https://sectionone.com/"},
        {"title": "Section 2", "url": "https://sectiontwo.com/"},
    ]
}

You can also add menu items that appear on hover below the section headings. To add these, use the entries key on a section:

html_theme_options = {
    "faculty_navbar": True,
    "faculty_navbar_root": "https://docs.faculty.ai/",
    "faculty_navbar_content": [
        {
            "title": "Section 1",
            "url": "https://sectionone.com/",
            "entries": [
                {
                    "title": "Section 1.1",
                    "url": "https://sectionone.com/one",
                },
                {
                    "title": "Section 1.2",
                    "url": "https://sectionone.com/one",
                },
            ]
        },
        {"title": "Section 2", "url": "https://sectiontwo.com/"},
    ]
}

It's also possible to mark sections and entries as external, meaning they will open in a separate tab, or to omit the URL entirely for e.g. section headings:

html_theme_options = {
    "faculty_navbar": True,
    "faculty_navbar_root": "https://docs.faculty.ai/",
    "faculty_navbar_content": [
        {
            "title": "No URL",
            "entries": [
                {
                    "title": "External link",
                    "url": "https://external.com/",
                    "external": True
                },
            ]
        },
        {"title": "Section 2", "url": "https://sectiontwo.com/"},
    ]
}