A clean customizable documentation theme for Sphinx

Overview

Furo

A clean customisable Sphinx documentation theme.

Demo image

Elevator pitch

  • Intentionally minimal --- the most important thing is the content, not the scaffolding around it.
  • Responsive --- adapting perfectly to the available screen space, to work on all sorts of devices.
  • Customisable --- change the color palette, font families, logo and more!
  • Easy to navigate --- with carefully-designed sidebar navigation and inter-page links.
  • Good looking content --- through clear typography and well-stylised elements.
  • Good looking search --- helps readers find what they want quickly.
  • Biased for smaller docsets --- intended for smaller documentation sets, where presenting the entire hierarchy in the sidebar is not overwhelming.

Quickstart

Furo is distributed on PyPI. To use the theme in your Sphinx project:

  1. Install Furo in documentation's build environment.

    pip install furo
    
  2. Update the html_theme in conf.py.

    html_theme = "furo"
  3. Your Sphinx documentation's HTML pages will now be generated with this theme! 🎉

For more information, visit Furo's documentation.

Contributing

Furo is a volunteer maintained open source project, and we welcome contributions of all forms. Please take a look at our Contributing Guide for more information.

Acknowledgements

Furo is inspired by (and borrows elements from) some excellent technical documentation themes:

We use BrowserStack to test on real devices and browsers. Shoutout to them for supporting OSS projects!

What's with the name?

I plucked this from the scientific name for Domesticated Ferrets: Mustela putorius furo.

A ferret is actually a really good spirit animal for this project: cute, small, steals little things from various places, and hisses at you when you try to make it do things it doesn't like.

I plan on commissioning a logo for this project (or making one myself) consisting of a cute ferret. Please reach out if you're interested!

Used By

I'm being told that mentioning who uses $thing is a good way to promote $thing.

License

This project is licensed under the MIT License.

Comments
  • Dark Mode Scrollbar on Linux + Blink

    Dark Mode Scrollbar on Linux + Blink

    There's currently no styling for the scroll bar in darkmode which causes it to stand out more than it should:

    image light image dark

    I'm currently using some custom CSS to produce the following scroll bar looks:

    image light image dark

    The CSS itself is below. I've just used colors from the available CSS variables, so the look could be improved by adding new ones:

    ::-webkit-scrollbar {
      width: 16px;
      height: 16px;
    }
    
    ::-webkit-scrollbar-corner,
    ::-webkit-scrollbar-track {
      background-color: var(--color-background-border);
    }
    
    ::-webkit-scrollbar-thumb {
      background-color: var(--color-foreground-border);
      background-clip: padding-box;
      border: 2px solid transparent;
    }
    
    /* Buttons */
    ::-webkit-scrollbar-button:single-button {
      background-color: var(--color-background-border);
      display: block;
      background-size: 10px;
      background-repeat: no-repeat;
    }
    
    /* Up */
    ::-webkit-scrollbar-button:single-button:vertical:decrement {
      height: 12px;
      width: 16px;
      background-position: center 4px;
      background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='100' height='100' fill='var(--color-background-border)'><polygon points='50,00 0,50 100,50'/></svg>");
    }
    
    /* Down */
    ::-webkit-scrollbar-button:single-button:vertical:increment {
      height: 12px;
      width: 16px;
      background-position: center 2px;
      background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='100' height='100' fill='var(--color-background-border)'><polygon points='0,0 100,0 50,50'/></svg>");
    }
    
    /* Left */
    ::-webkit-scrollbar-button:single-button:horizontal:decrement {
      height: 12px;
      width: 12px;
      background-position: 3px 3px;
      background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='100' height='100' fill='var(--color-background-border)'><polygon points='0,50 50,100 50,0'/></svg>");
    }
    
    /* Right */
    ::-webkit-scrollbar-button:single-button:horizontal:increment {
      height: 12px;
      width: 12px;
      background-position: 3px 3px;
      background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='100' height='100' fill='var(--color-background-border)'><polygon points='0,0 0,100 50,50'/></svg>");
    }
    
    enhancement 
    opened by rmorshea 22
  • Customization to select light/dark/dual mode

    Customization to select light/dark/dual mode

    Is your feature request related to a problem? Please describe. A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

    Currently, I think by default furo adapts to OS (or browser) settings to display light/dark mode. I'll be nice if we can choose to render only light mode, or only dark mode, or both like the present default.

    Describe the solution you'd like A clear and concise description of what you want to happen.

    Something like a setting in conf.py for the preferred action?

    html_theme_options = {
        "theme-color": light/dark/dual,
    }
    

    Describe alternatives you've considered A clear and concise description of any alternative solutions or features you've considered.

    Stick with the current default. :)

    enhancement help wanted needs discussion 
    opened by pavithraes 21
  • Roadmap to stable release

    Roadmap to stable release

    This issue is meant to be a planning/dumping ground for tasks that have to be done prior to the first stable release of furo.

    • [x] Write the documentation for this theme
      • [x] Finalize skeleton structure.
      • [x] Write the content!
    • [x] Deploy the documentation w/ GitHub Pages
    • [x] Stylize API documentation
    • [x] Stylize captions
    • [x] Stylize field lists (low priority)
    • [x] Stylize the remaining permalinks
    • [x] Switch to em for typography, instead of using rem everywhere
    • [x] Tweak spacing for headings & paragraphs -- they might have a little too much margin?
    • [x] Fix page's height on mobile, where 100%-100vh is not 0. -.-
    • [x] Fix z-index levels for overlay (the toctree overlay needs to be above the sidebar and vice-versa).
    • [x] Skeleton + styling for index pages (#50)
    • [x] ~Add JS-based buttons to copy code blocks~
    • [x] ~Create a good looking landing page for the documentation~
    opened by pradyunsg 17
  • Add user end customizability for code block coloring and highlighting of the inline code block

    Add user end customizability for code block coloring and highlighting of the inline code block

    Is your feature request related to a problem? Please describe. The current variable that controls the highlighting of the inline code block and general code block coloring always looks out of place: image (this screenshot is from the PhotonVision documentation)

    Describe the solution you'd like CSS variable that the user can control in conf.py to change both of these.

    Describe alternatives you've considered Have a set color that is used for light/dark mode that cannot be controlled by the user but still would fit in.

    enhancement needs info 
    opened by mdurrani808 16
  • Instructions to change the dark mode code block styling don't work

    Instructions to change the dark mode code block styling don't work

    URL: https://pradyunsg.me/furo/customisation/colors/#code-block-styling

    What is missing or inaccurate about the content on this page?

    Not sure if this is a doc issue or a bug. Instructions to change the dark mode code block styling don't work. (They do work for light mode.) Tested using Sphinx==3.3.1 and furo==2020.12.9b21, the latest versions released on PyPI.

    I pasted these lines in my docs/conf.py used by Sphinx.

    pygments_style = "sphinx"
    pygments_dark_style = "monokai"
    

    Changing pygments_style to another valid Pygments style affects the syntax highlighting in light mode when I rebuild the docs with Sphinx, but changing pygments_dark_style doesn't do anything. Dark mode is always the same style.

    bug documentation 
    opened by gilch 16
  • Make the top of page more easily reachable

    Make the top of page more easily reachable

    The right-hand-side navigation doesn't have a way to go on top of page.

    Example: https://pradyunsg.me/furo/customisation/

    By using the right links, you can go at "Theme options" most. If there is a lot of content between Customisation and Theme options you cannot access that section of page via that menu.

    Would you feel useful to have "Customisation" there too?

    enhancement needs discussion 
    opened by dvarrazzo 15
  • Add styling for non-panel parts of sphinx-panels

    Add styling for non-panel parts of sphinx-panels

    Describe the bug sphinx-panels dropdown directive does not respect dark mode if it is not within a panels directive

    To Reproduce sorry I don't have a full repro, but here's the page I used to test this

    Bug
    ===
    
    .. panels::
    
        Content of the top-left panel
    
        ---
    
        Content of the top-right panel
    
        :badge:`example,badge-primary`
    
        ---
    
        .. dropdown:: :fa:`eye,mr-1` Bottom-left panel
    
            Hidden content
    
        ---
    
        .. link-button:: https://example.com
            :text: Clickable Panel
            :classes: stretched-link
    
    
    .. dropdown:: Click on me to see my content!
    
        I'm the content which can be anything:
    
        .. link-button:: https://example.com
            :text: Like a Button
            :classes: btn-primary
    
    

    Expected behaviour The dropdown at the bottom of the page should also have a dark background

    Screenshots https://gyazo.com/b53f60444de0427d08b270a280f9784e https://gyazo.com/2ed3766faa9d43325e8b020311ad78a6

    Desktop (please complete the following information):

    • OS: macOS Big Sur 11.2.1
    • Browser: safari
    • Version: 14.0.3

    Additional context Using the latest PyPi version for both Furo and sphinx-panels

    enhancement help wanted 
    opened by RobertCraigie 14
  • Error when using JSON builder

    Error when using JSON builder

    Hi. Thanks for the lovely project!

    The furo theme is not compatible currently with the json builder.

    Steps to reproduce the behavior:

    1. Create a project and enable the furo theme.
    2. make html (Observe no problem)
    3. make json (Error: see below)
    4. Comment out furo theme
    5. make json (Observe no problem)

    At step three, the end of the traceback is:

      File "/env/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 360, in build
        self.write(docnames, list(updated_docnames), method)
      File "/env/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 534, in write
        self._write_serial(sorted(docnames))
      File "/env/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 544, in _write_serial
        self.write_doc(docname, doctree)
      File "/env/lib/python3.8/site-packages/sphinx/builders/html/__init__.py", line 611, in write_doc
        self.handle_page(docname, ctx, event_arg=doctree)
      File "/env/lib/python3.8/site-packages/sphinxcontrib/serializinghtml/__init__.py", line 104, in handle_page
        self.dump_context(ctx, outfilename)
      File "/env/lib/python3.8/site-packages/sphinxcontrib/serializinghtml/__init__.py", line 79, in dump_context
        self.implementation.dump(context, ft, *self.additional_dump_args)
      File "/env/lib/python3.8/site-packages/sphinxcontrib/serializinghtml/jsonimpl.py", line 31, in dump
        json.dump(obj, fp, *args, **kwds)
      File "/Users/carlton/.pyenv/versions/3.8.3/lib/python3.8/json/__init__.py", line 179, in dump
        for chunk in iterable:
      File "/Users/carlton/.pyenv/versions/3.8.3/lib/python3.8/json/encoder.py", line 431, in _iterencode
        yield from _iterencode_dict(o, _current_indent_level)
      File "/Users/carlton/.pyenv/versions/3.8.3/lib/python3.8/json/encoder.py", line 405, in _iterencode_dict
        yield from chunks
      File "/Users/carlton/.pyenv/versions/3.8.3/lib/python3.8/json/encoder.py", line 438, in _iterencode
        o = _default(o)
      File "/env/lib/python3.8/site-packages/sphinxcontrib/serializinghtml/jsonimpl.py", line 25, in default
        return super().default(obj)
      File "/.pyenv/versions/3.8.3/lib/python3.8/json/encoder.py", line 179, in default
        raise TypeError(f'Object of type {o.__class__.__name__} '
    TypeError: Object of type _lru_cache_wrapper is not JSON serializable
    

    Expected behavior The JSON builder should succeed.

    • Version: furo==2021.2.21b25
    bug 
    opened by carltongibson 13
  • Spacing issues in API docs

    Spacing issues in API docs

    Describe the bug

    Longer API (autodoc) documentation looks squeezed.

    To Reproduce

    Use something like .. automethod with a params that are multiple paragraphs, possibly contain ordered or unordered lists.

    Expected behavior

    It would be great to get some spacing.

    Screenshots

    Screenshot 2020-09-28 at 12 04 29@2x

    It looks especially unfortunate when having multiple short paragraphs:

    Screenshot 2020-09-28 at 12 05 24@2x

    Lists also look unhappy without any social distancing:

    Screenshot 2020-09-28 at 12 05 52@2x

    Desktop (please complete the following information):

    • OS: macOS
    • Browser Safari
    • Version 14

    Otherwise great work!

    bug 
    opened by hynek 12
  • Replace domainindex.html with (more-or-less) the sphinx-doc/sphinx version

    Replace domainindex.html with (more-or-less) the sphinx-doc/sphinx version

    This is copied from https://github.com/sphinx-doc/sphinx/blob/3.x/sphinx/themes/basic/domainindex.html and then edited to extend base.html rather than layout.html.

    I thought I'd already tried something similar to this, but obviously not!

    This seems to work, but maybe further work is needed in order fully to integrate it into the theme.

    opened by wlupton 11
  • Allow adding **local** table of contents without the error message

    Allow adding **local** table of contents without the error message

    Is your feature request related to a problem? Please describe. I understand that it doesn't make much sense to have a full table of contents as furo already shows full ToC on the sidebar and I'm assuming this is why such an error message exists, but I don't think those reasons are as valid for the local table of contents. A local table of contents can be useful to, for example, list the options available to the user more clearly.

    Describe the solution you'd like I think hiding the message only for the local table of contents would be a great solution to this problem.

    Describe alternatives you've considered If you don't agree that having a local table of contents can be useful then a possible alternative would be to have a theme setting that you have to opt into to disable the error (fully or just for the local table of contents, whatever is easier or is of your preference).

    Additional context Links to some examples of docs pages where we would like to use the local table of contents: https://red-discordbot--4675.org.readthedocs.build/en/4675/install_windows.html image https://red-discordbot--4675.org.readthedocs.build/en/4675/install_linux_mac.html image

    enhancement needs discussion 
    opened by Jackenmen 11
  • Hide

    Hide "Contents" on pages with multiple TOC trees

    If a document has more than one TOC tree directive and no other headings on the page, an empty "Contents" section is rendered in the sidebar. Adjusting the hide-toc logic to check if all entries in the TOC tree are all local TOC tree entries.

    opened by jdknight 2
  • Allow HTML in the copyright message

    Allow HTML in the copyright message

    It would be nice to allow HTML in the copyright so that you can link to a website, like so:

    copyright = "<a href=\"https://jareddillard.com\">Jared Dillard</a>"
    

    Screenshot from 2022-12-22 23-00-44

    I don't know if this creates a security risk by using safe, but if it does I think you'd have to try and shoot yourself in the foot. I'm also not sure if docs of some kind should be added to point out that use can use HTML (carefully).

    opened by jdillard 1
  • Increase admonition title background opacity

    Increase admonition title background opacity

    Description

    This PR increases the admonition title background opacity from 10% to 20%, resulting in a more vibrant mood and smoother contrast. If desired this value could even be raised to 25 or even 30 percent, although that may draw more attention than wanted.

    Rationale

    Currently, admonition title backgrounds are quite dark. When compared to the 100% opacity left border, there is a high contrast that looks out of place upon further inspection. The current opacity doesn't give enough overall contrast to the document as a whole, and therefore doesn't draw as much attention as you would expect from an admonition. Increasing the background opacity decreases the sharp contrast between the border and background, while increasing the overall contrast just enough to draw the eye to land on the admonition title, but doesn't draw the eye too much as to disrupt the flow of the document. Overall, it gives admonitions (particularly warnings and danger messages) the importance they deserve without seeming out of place.

    opened by BobDotCom 0
  • Increase icon sizes

    Increase icon sizes

    Description

    This PR increases the size of some icons in order to improve accessibility, particularly for mobile devices. The larger sizes only consume a slightly larger horizontal width, while the vertical width is mainly unchanged due to padding/margin - which is great, because it only takes up previously empty space. I've included some before/after comparison images below.

    Rationale

    I've found that on mobile the menu icons are harder to tap than they should be, and compared to honestly most other websites the proportions just look and feel unnatural. I've even had difficulty clicking the icons on desktop sometimes. These new sizes make the site feel more modern and easy to use.

    Mobile

    Header

    • Before Screen Shot 2022-10-15 at 7 52 55 PM
    • After Screen Shot 2022-10-15 at 7 53 24 PM

    Footer

    • Before Screen Shot 2022-10-15 at 7 54 10 PM
    • After Screen Shot 2022-10-15 at 7 54 57 PM

    Desktop

    Header (Wide)

    • Before Screen Shot 2022-10-15 at 6 43 04 PM
    • After Screen Shot 2022-10-15 at 6 44 14 PM

    Header (Narrow)

    • Before Screen Shot 2022-10-15 at 7 49 53 PM

    • After Screen Shot 2022-10-15 at 7 50 23 PM

    Footer

    • Before Screen Shot 2022-10-15 at 6 45 57 PM
    • After Screen Shot 2022-10-15 at 6 46 26 PM
    opened by BobDotCom 1
  • Enable announcement banner to be sticky

    Enable announcement banner to be sticky

    What's happening?

    Currently, I use the announcement banner to warn users that they are looking at an outdated version of the generated docs. However, the banner is not sticky / fixed, so it disappears when users scroll down the page. This can be problematic when users access the docs through a hyperlink referencing a paragraph, as they probably won't see the banner.

    I tried using custom CSS to simply make the banner sticky, but it seems it seems more complex (see discussion #545). In particular, the rest of the page will scroll under the banner, eventually hiding the logo, which I think is not the expected behaviour. Screenshot from 2022-10-08 18-24-04

    Reproducer

    Simply use announcement option and scroll down.

    Expectation

    In my opinion, banners should be sticky by default in order to prevent this, but I guess having an option to make them sticky or not could be nice! :slightly_smiling_face:

    Code of Conduct

    enhancement 
    opened by alexisthual 0
Releases(2022.12.07)
Owner
Pradyun Gedam
@pypa member, @psf fellow, @toml-lang core, @sphinx-doc contributor. Was intern at @enthought and IIT Bombay.
Pradyun Gedam
Automated generation of real Swagger/OpenAPI 2.0 schemas from Django REST Framework code.

drf-yasg - Yet another Swagger generator Generate real Swagger/OpenAPI 2.0 specifications from a Django Rest Framework API. Compatible with Django Res

Cristi Vîjdea 3k Dec 31, 2022
The sarge package provides a wrapper for subprocess which provides command pipeline functionality.

Overview The sarge package provides a wrapper for subprocess which provides command pipeline functionality. This package leverages subprocess to provi

Vinay Sajip 14 Dec 18, 2022
Żmija is a simple universal code generation tool.

Żmija Żmija is a simple universal code generation tool. It is intended to be used as a means to generate code that is both efficient and easily mainta

Adrian Samoticha 2 Nov 23, 2021
Elliptic curve cryptography (ed25519) beginner tutorials in Python 3

ed25519_tutorials Elliptic curve cryptography (ed25519) beginner tutorials in Python 3 Instructions Just download the repo and read the tutorial files

6 Dec 27, 2022
Contains the assignments from the course Building a Modern Computer from First Principles: From Nand to Tetris.

Contains the assignments from the course Building a Modern Computer from First Principles: From Nand to Tetris.

Matheus Rodrigues 1 Jan 20, 2022
A set of Python libraries that assist in calling the SoftLayer API.

SoftLayer API Python Client This library provides a simple Python client to interact with SoftLayer's XML-RPC API. A command-line interface is also in

SoftLayer 155 Sep 20, 2022
Highlight Translator can help you translate the words quickly and accurately.

Highlight Translator can help you translate the words quickly and accurately. By only highlighting, copying, or screenshoting the content you want to translate anywhere on your computer (ex. PDF, PPT

Coolshan 48 Dec 21, 2022
Exercism exercises in Python.

Exercism exercises in Python.

Exercism 1.3k Jan 04, 2023
DeltaPy - Tabular Data Augmentation (by @firmai)

DeltaPy⁠⁠ — Tabular Data Augmentation & Feature Engineering Finance Quant Machine Learning ML-Quant.com - Automated Research Repository Introduction T

Derek Snow 470 Dec 28, 2022
Run `black` on python code blocks in documentation files

blacken-docs Run black on python code blocks in documentation files. install pip install blacken-docs usage blacken-docs provides a single executable

Anthony Sottile 460 Dec 23, 2022
Flask-Rebar combines flask, marshmallow, and swagger for robust REST services.

Flask-Rebar Flask-Rebar combines flask, marshmallow, and swagger for robust REST services. Features Request and Response Validation - Flask-Rebar reli

PlanGrid 223 Dec 19, 2022
Credit EDA Case Study Using Python

This case study aims to identify patterns which indicate if a client has difficulty paying their installments which may be used for taking actions such as denying the loan, reducing the amount of loa

Purvi Padliya 1 Jan 14, 2022
:blue_book: Automatic documentation from sources, for MkDocs.

mkdocstrings Automatic documentation from sources, for MkDocs. Features - Python handler - Requirements - Installation - Quick usage Features Language

1.1k Jan 04, 2023
A collection and example code of every topic you need to know about in the basics of Python.

The Python Beginners Guide: Master The Python Basics Tonight This guide is a collection of every topic you need to know about in the basics of Python.

Ahmed Baari 1 Dec 19, 2021
[Unofficial] Python PEP in EPUB format

PEPs in EPUB format This is a unofficial repository where I stock all valid PEPs in the EPUB format. Repository Cloning git clone --recursive Mickaël Schoentgen 9 Oct 12, 2022

This is the data scrapped of all the pitches made up potential startup's to established bussiness tycoons of India with all the details of Investments made, equity share, Name of investor etc.

SharkTankInvestor This is the data scrapped of all the pitches made up potential startup's to established bussiness tycoons of India with all the deta

Subradip Poddar 2 Aug 02, 2022
Repository for learning Python (Python Tutorial)

Repository for learning Python (Python Tutorial) Languages and Tools 🧰 Overview 📑 Repository for learning Python (Python Tutorial) Languages and Too

Swiftman 2 Aug 22, 2022
100 Days of Code Learning program to keep a habit of coding daily and learn things at your own pace with help from our remote community.

100 Days of Code Learning program to keep a habit of coding daily and learn things at your own pace with help from our remote community.

Git Commit Show by Invide 41 Dec 30, 2022
Project created to help beginner programmers to study, despite the lack of internet!

Project created to help beginner programmers to study, despite the lack of internet!

Dev4Dev 2 Oct 25, 2021
A course-planning, course-map rendering and GPA-calculation web service, designed for the SFU (Simon Fraser University) student.

SFU Course Planner What is the overall goal of the project (i.e. what does it do, or what problem is it solving)? As the title suggests, this project

Ash Peng 1 Oct 21, 2021