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
Sphinx theme for readthedocs.org

Read the Docs Sphinx Theme This Sphinx theme was designed to provide a great reader experience for documentation users on both desktop and mobile devi

Read the Docs 4.3k Dec 31, 2022
Sphinx Bootstrap Theme

Sphinx Bootstrap Theme This Sphinx theme integrates the Bootstrap CSS / JavaScript framework with various layout options, hierarchical menu navigation

Ryan Roemer 584 Nov 16, 2022
Main repository for the Sphinx documentation builder

Sphinx Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of mul

null 5.1k Jan 2, 2023
A curated list of awesome tools for Sphinx Python Documentation Generator

Awesome Sphinx (Python Documentation Generator) A curated list of awesome extra libraries, software and resources for Sphinx (Python Documentation Gen

Hyunjun Kim 831 Dec 27, 2022
Main repository for the Sphinx documentation builder

Sphinx Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of mul

null 5.1k Jan 4, 2023
Watch a Sphinx directory and rebuild the documentation when a change is detected. Also includes a livereload enabled web server.

sphinx-autobuild Rebuild Sphinx documentation on changes, with live-reload in the browser. Installation sphinx-autobuild is available on PyPI. It can

Executable Books 440 Jan 6, 2023
📖 Generate markdown API documentation from Google-style Python docstring. The lazy alternative to Sphinx.

lazydocs Generate markdown API documentation for Google-style Python docstring. Getting Started • Features • Documentation • Support • Contribution •

Machine Learning Tooling 118 Dec 31, 2022
Seamlessly integrate pydantic models in your Sphinx documentation.

Seamlessly integrate pydantic models in your Sphinx documentation.

Franz Wöllert 71 Dec 26, 2022
Numpy's Sphinx extensions

numpydoc -- Numpy's Sphinx extensions This package provides the numpydoc Sphinx extension for handling docstrings formatted according to the NumPy doc

NumPy 234 Dec 26, 2022
ReStructuredText and Sphinx bridge to Doxygen

Breathe Packagers: PGP signing key changes for Breathe >= v4.23.0. https://github.com/michaeljones/breathe/issues/591 This is an extension to reStruct

Michael Jones 643 Dec 31, 2022
Type hints support for the Sphinx autodoc extension

sphinx-autodoc-typehints This extension allows you to use Python 3 annotations for documenting acceptable argument types and return value types of fun

Alex Grönholm 462 Dec 29, 2022
sphinx builder that outputs markdown files.

sphinx-markdown-builder sphinx builder that outputs markdown files Please ★ this repo if you found it useful ★ ★ ★ If you want frontmatter support ple

Clay Risser 144 Jan 6, 2023
A powerful Sphinx changelog-generating extension.

What is Releases? Releases is a Python (2.7, 3.4+) compatible Sphinx (1.8+) extension designed to help you keep a source control friendly, merge frien

Jeff Forcier 166 Dec 29, 2022
Speed up Sphinx builds by selectively removing toctrees from some pages

Remove toctrees from Sphinx pages Improve your Sphinx build time by selectively removing TocTree objects from pages. This is useful if your documentat

Executable Books 8 Jan 4, 2023
python package sphinx template

python-package-sphinx-template python-package-sphinx-template

Soumil Nitin Shah 2 Dec 26, 2022
epub2sphinx is a tool to convert epub files to ReST for Sphinx

epub2sphinx epub2sphinx is a tool to convert epub files to ReST for Sphinx. It uses Pandoc for converting HTML data inside epub files into ReST. It cr

Nihaal 8 Dec 15, 2022
A `:github:` role for Sphinx

sphinx-github-role A github role for Sphinx. Usage Basic usage MyST: :caption: index.md See {github}`astrojuanlu/sphinx-github-role#1`. reStructuredT

Juan Luis Cano Rodríguez 4 Nov 22, 2022
This is a template (starter kit) for writing Maturity Work with Sphinx / LaTeX at Collège du Sud

sphinx-tm-template Ce dépôt est un template de base utilisable pour écrire ton travail de maturité dans le séminaire d'informatique du Collège du Sud.

null 6 Dec 22, 2022
A Material Design theme for MkDocs

A Material Design theme for MkDocs Create a branded static site from a set of Markdown files to host the documentation of your Open Source or commerci

Martin Donath 12.3k Jan 4, 2023