conf.py
High-level description
This file, docs/conf.py, is a configuration file for Sphinx, a documentation generation tool. It sets up various options and extensions for building the documentation for the Cassiopeia project, including autodoc, intersphinx, and custom extensions for generating API documentation.
Code Structure
The code is structured as a series of configuration settings for Sphinx. It imports necessary modules, sets up paths, and configures various Sphinx extensions and options. The file also defines a custom AutoAutoSummary class for generating summaries of class methods and attributes.
Symbols
Configuration Settings
Description
Various configuration settings for Sphinx are defined throughout the file. These include:
- Path setup
- Extension configuration
- Project information
- HTML output options
- Intersphinx mapping
- Custom CSS and static files
Inputs
N/A
Outputs
N/A
AutoAutoSummary
Description
A custom Sphinx directive that automatically generates summaries for class methods and attributes.
Inputs
| Name | Type | Description |
|---|---|---|
| clazz | str | The fully qualified name of the class to summarize |
Outputs
| Name | Type | Description |
|---|---|---|
| content | list | A list of method or attribute names to be included in the summary |
Internal Logic
- Parses the class name from the input
- Imports the class
- Retrieves methods or attributes based on the options provided
- Generates a list of content items for the summary
setup
Description
A function to set up the Sphinx application by adding the custom AutoAutoSummary directive.
Inputs
| Name | Type | Description |
|---|---|---|
| app | Sphinx application | The Sphinx application instance |
Outputs
N/A
Dependencies
| Dependency | Purpose |
|---|---|
| sphinx | Main documentation generation tool |
| nbsphinx | Jupyter notebook integration |
| sphinx_autodoc_typehints | Type hints in documentation |
| scanpydoc | Additional documentation utilities |
| pydata_sphinx_theme | HTML theme for documentation |
Configuration
| Option | Type | Default | Description |
|---|---|---|---|
| needs_sphinx | str | “3.4” | Minimum required Sphinx version |
| extensions | list | […] | List of Sphinx extensions to use |
| exclude_patterns | list | [“_build”, “**.ipynb_checkpoints”] | Patterns to exclude from documentation |
| autodoc_mock_imports | list | [“gurobipy”] | Modules to mock for autodoc |
| html_theme | str | “pydata_sphinx_theme” | HTML theme to use |
TODOs
- The commented out line
# "scanpydoc.autosummary_generate_imported",suggests a potential future addition to the extensions list.