https://github.com/facultyai/faculty-sphinx-theme
A Sphinx theme for Faculty projects
https://github.com/facultyai/faculty-sphinx-theme
python sphinx
Last synced: about 1 year ago
JSON representation
A Sphinx theme for Faculty projects
- Host: GitHub
- URL: https://github.com/facultyai/faculty-sphinx-theme
- Owner: facultyai
- Created: 2020-04-09T17:33:09.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2023-04-17T13:41:18.000Z (about 3 years ago)
- Last Synced: 2024-03-25T20:20:49.824Z (about 2 years ago)
- Topics: python, sphinx
- Language: CSS
- Homepage: https://docs.faculty.ai/
- Size: 32.2 KB
- Stars: 5
- Watchers: 7
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.rst
- License: LICENSE-2.0.txt
Awesome Lists containing this project
README
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
------------
.. code-block:: bash
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:
.. code-block:: python
extensions = [
"faculty_sphinx_theme",
# Plus any other extensions you are using
]
and modify the ``html_theme`` setting to:
.. code-block:: python
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":
.. code-block:: python
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:
.. code-block:: python
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:
.. code-block:: python
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:
.. code-block:: python
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/"},
]
}