​
High-level description

This directory contains custom documentation-related files for the Streamlink project. It includes CSS files for styling the documentation, custom Sphinx templates, configuration files, and extensions to enhance the documentation generation process.

​
What does it do?

The contents of this directory work together to customize and improve the appearance and functionality of Streamlink’s documentation. Here’s a breakdown of the main components:
  1. CSS files: These customize the appearance of the documentation, overriding default styles and enhancing readability.
  2. Custom templates: These modify the layout of the documentation pages, including font specifications.
  3. Configuration file: This sets up various options for the Sphinx documentation generator.
  4. Custom extension: This enhances the parsing of docstrings, particularly for the “Returns” section.
Together, these components create a cohesive, visually appealing, and informative documentation experience for Streamlink users and contributors.

​
Key Files

  1. _static/override.css: This is the main CSS file that overrides the default styles of the Furo Sphinx theme. It customizes the appearance of code blocks, citations, headings, buttons, and other elements specific to Streamlink’s documentation.
  2. _static/sphinx_gallery.css: This CSS file focuses on styling Sphinx Gallery thumbnails, improving their visual presentation within the documentation.
  3. _templates/layout.html: This custom template inherits from the PyData Sphinx theme and overrides the fonts block to specify custom font families for the body and header elements.
  4. conf.py: This is the main configuration file for Sphinx. It sets various options for the documentation generation process, including theme settings, extensions, and autodoc options.
  5. extensions/typed_returns.py: This custom Sphinx extension enhances the parsing of the “Returns” section in NumPy-style docstrings, formatting return values with hyperlinks to their types.

​
Dependencies

The documentation system relies on several key dependencies:
  1. Sphinx: The main documentation generator.
  2. Furo Sphinx theme: The base theme that override.css customizes.
  3. PyData Sphinx theme: Used as a base for the custom layout template.
  4. Sphinx Gallery: Provides the HTML structure and classes targeted by sphinx_gallery.css.
  5. Napoleon extension: Used for parsing NumPy-style docstrings.

​
Configuration

The conf.py file contains various configuration options for Sphinx, including:
  1. Project information (name, version, etc.)
  2. General configuration (extensions, templates path, etc.)
  3. HTML output options (theme, static files, etc.)
  4. Theme-specific options
  5. Autodoc options
The CSS files (override.css and sphinx_gallery.css) contain numerous style rules that target specific elements of the documentation. These rules customize the appearance of various components, such as code blocks, citations, buttons, and Sphinx Gallery thumbnails. The custom extension in typed_returns.py modifies the behavior of the NumpyDocstring class to enhance the formatting of the “Returns” section in docstrings. It adds hyperlinks to the types of return values using the :class: role. Overall, this directory provides a comprehensive set of tools and configurations to create a polished, user-friendly documentation experience for the Streamlink project.