API Reference

Python API

yardang.build

Generate Sphinx documentation configuration from pyproject.toml.

A context manager that creates a temporary Sphinx configuration (conf.py) based on settings from pyproject.toml and yields the configuration directory path for use with sphinx-build. If a conf.py already exists in the current directory, it yields the current directory instead.

Configuration is read from the [tool.yardang] section of pyproject.toml by default, with breathe/doxygen settings in [tool.yardang.breathe].

Parameters:

project Project name. Falls back to [project].name or directory name.
title Documentation title. Falls back to [tool.yardang].title or project name.
module Python module name for autoapi. Falls back to project name with hyphens replaced by underscores.
description Project description for metadata.
author Author name. Falls back to first entry in [project].authors.
copyright Copyright string. Falls back to author name.
version Version string. Falls back to [project].version.
theme Sphinx theme name. Defaults to "furo".
docs_root Base URL for hosted documentation. Used for canonical URLs.
root Path to README or index file to use as documentation root.
source_dir Existing Sphinx source directory. When set, root names an existing document relative to this directory and no index is generated.
cname Custom domain name for GitHub Pages CNAME file.
pages List of page paths to include in the toctree.
use_autoapi Whether to use sphinx-autoapi for Python API docs. Defaults to None (auto-detect).
custom_css Path or raw content for custom CSS. When unset, falls back to a bundled per-theme {theme}.css then the generic custom.css.
custom_js Path or raw content for custom JS. When unset, falls back to a bundled per-theme {theme}.js then the generic custom.js.
html_output_dir Directory where Sphinx writes HTML output. Custom CSS/JS are placed under <html_output_dir>/_static. Defaults to docs/html.
config_base Base key in pyproject.toml for configuration. Defaults to "tool.yardang".
previous_versions Whether to generate previous versions documentation.
adjust_arguments Callback to modify template arguments before rendering. Receives the args dict and should return the modified dict.
adjust_template Callback to modify the Jinja2 template before rendering. Receives the template and should return the modified template.

Yields:

str

Path to directory containing the generated conf.py file,: or the current directory if conf.py already exists.

Raises:

toml.TomlDecodeError If pyproject.toml is malformed.

Example

Basic usage with sphinx-build:

from yardang import generate_docs_configuration

with generate_docs_configuration() as config_dir:
    subprocess.run(["sphinx-build", "-c", config_dir, ".", "docs/html"])

With custom arguments callback:

def customize(args):
    args["html_theme_options"]["sidebar_hide_name"] = True
    return args

with generate_docs_configuration(adjust_arguments=customize) as config_dir:
    # build docs...

Note

Breathe/Doxygen configuration is loaded from [tool.yardang.breathe] with the following options:

projects: Dict mapping project names to Doxygen XML directories
default-project: Default project for breathe directives
domain-by-extension: Map file extensions to Sphinx domains
show-define-initializer: Show macro initializer values (default: True)
show-enumvalue-initializer: Show enum value initializers (default: True)
show-include: Show #include directives (default: True)
use-project-refids: Prefix refids with project name (default: True)

yardang.build.generate_wiki_configuration(*, project: str = '', title: str = '', module: str = '', description: str = '', author: str = '', copyright: str = '', version: str = '', theme: str = 'furo', docs_root: str = '', root: str = '', cname: str = '', pages: list | None = None, use_autoapi: bool | None = None, autoapi_ignore: list | None = None, custom_css: Path | None = None, custom_js: Path | None = None, config_base: str = 'tool.yardang', previous_versions: bool | None = False, adjust_arguments: Callable | None = None, adjust_template: Callable | None = None)[source]

Generate Sphinx configuration for GitHub Wiki markdown output.

A context manager similar to generate_docs_configuration, but configured for building markdown output suitable for GitHub Wiki using sphinx-markdown-builder.

This adds the sphinx_markdown_builder extension and sets appropriate options for GitHub-flavored markdown output.

Parameters:

project Project name. Falls back to [project].name or directory name.
title Documentation title. Falls back to [tool.yardang].title or project name.
module Python module name for autoapi. Falls back to project name with hyphens replaced by underscores.
description Project description for metadata.
author Author name. Falls back to first entry in [project].authors.
copyright Copyright string. Falls back to author name.
version Version string. Falls back to [project].version.
theme Sphinx theme name. Defaults to "furo".
docs_root Base URL for hosted documentation. Used for canonical URLs.
root Path to README or index file to use as documentation root.
cname Custom domain name for GitHub Pages CNAME file.
pages List of page paths to include in the toctree.
use_autoapi Whether to use sphinx-autoapi for Python API docs.
custom_css Path to custom CSS file.
custom_js Path to custom JavaScript file.
config_base Base key in pyproject.toml for configuration.
previous_versions Whether to generate previous versions documentation.
adjust_arguments Callback to modify template arguments before rendering.
adjust_template Callback to modify the Jinja2 template before rendering.

Yields:

tuple

(config_dir, wiki_args) where config_dir is the path to the directory: containing the generated conf.py file, and wiki_args is a dict with wiki configuration for post-processing.

yardang.build.run_doxygen_if_needed(breathe_projects: dict[str, str], *, force: bool = False, quiet: bool = False) → dict[str, bool][source]

Run doxygen for breathe projects if needed.

For each project in breathe_projects, checks if the XML output directory exists. If not, attempts to find a Doxyfile in the parent directory and runs doxygen to generate the XML.

Parameters:

breathe_projects Dict mapping project names to XML output directories.
force If True, run doxygen even if XML directory already exists.
quiet If True, suppress doxygen output.

Returns:

Dict mapping project names to whether doxygen was run successfully. Returns empty dict if doxygen is not installed.

Example

>>> results = run_doxygen_if_needed({"mylib": "docs/xml"})
>>> if results.get("mylib"):
...     print("Doxygen ran successfully")

yardang.build.theme_module(theme: str) → str[source]: Return the importable module that provides theme.

yardang.cli

yardang.cli.build(*, quiet: bool = False, debug: bool = False, pdb: bool = False, warning_is_error: bool = False, project: str | None = None, title: str | None = None, module: str | None = None, description: str | None = None, author: str | None = None, copyright: str | None = None, version: str | None = None, theme: str | None = None, docs_root: str | None = None, root: str | None = None, source_dir: str | None = None, cname: str | None = None, pages: list[Path] | None = None, use_autoapi: bool | None = None, custom_css: Path | None = None, custom_js: Path | None = None, output: str = 'docs/html', config_base: str | None = 'tool.yardang', previous_versions: bool | None = False)[source]

yardang.cli.debug()[source]

yardang.cli.main()[source]

yardang.cli.preview(*, themes: list[str] | None = None, output: str = 'docs/html/_previews', quiet: bool = False, debug: bool = False, pdb: bool = False)[source]

Build the documentation once per theme for side-by-side comparison.

For each theme in themes (defaulting to the themes yardang bundles defaults for), the docs are rendered into <output>/<theme>. Themes whose Sphinx package is not installed are skipped with a warning.

Generate GitHub Wiki compatible markdown documentation.

Builds markdown output using sphinx-markdown-builder and post-processes it to be compatible with GitHub Wiki format, including: - Flattening directory structure - Renaming index.md to Home.md - Generating _Sidebar.md navigation - Generating _Footer.md - Fixing internal links

yardang.utils

class yardang.utils.HtmlTitle[source]

Bases: str

A title carrying markup that degrades to plain text for the <title> tag.

Themes render docstitle into the header verbatim but escape it for the browser tab; __html__ is what the |e and |striptags filters pick up.

yardang.utils.get_config(section='', base='tool.yardang')[source]

yardang.utils.get_config_flex(section='', base='tool.yardang')[source]

Look up a config key, accepting both hyphens and underscores.

Tries the hyphenated form first (TOML convention), then the underscored form (Sphinx convention). For example, looking up html_extra_path will try html-extra-path first, then html_extra_path.

C++ Example

This is an example of documenting C++ code using breathe integration.

Document Everything

Use doxygenindex to document all symbols from Doxygen XML:

class Calculator

#include <calculator.hpp>

A class for performing basic arithmetic operations.

The Calculator class provides methods for addition, subtraction, multiplication, and division. It also maintains a history of operations performed.

Example usage:

calc::Calculator calc;
double result = calc.add(5.0, 3.0);
std::cout << "Result: " << result << std::endl;

Note

This is a thread-safe implementation.

Subclassed by calc::ScientificCalculator

Public Functions

Calculator()

Default constructor.

Initializes an empty calculator with no operation history.

virtual ~Calculator(): Destructor.

double add(double a, double b)

Add two numbers.

See also

subtract()

Parameters:

a The first operand.
b The second operand.

Returns:

The sum of a and b.

double subtract(double a, double b)

Subtract two numbers.

See also

add()

Parameters:

a The minuend.
b The subtrahend.

Returns:

The difference (a - b).

double multiply(double a, double b)

Multiply two numbers.

See also

divide()

Parameters:

a The first factor.
b The second factor.

Returns:

The product of a and b.

double divide(double a, double b)

Divide two numbers.

See also

multiply()

Warning

Division by zero will throw an exception.

Parameters:

a The dividend.
b The divisor.

Throws:

std::invalid_argument if b is zero.

Returns:

The quotient (a / b).

std::vector<OperationResult> getHistory() const

Get the history of all operations.

Returns:: A vector containing all operation results.

void clearHistory(): Clear the operation history.

size_t getOperationCount() const

Get the number of operations performed.

Returns:: The count of operations in history.

Protected Functions

void recordOperation(const OperationResult &result)

Record an operation in the history.

Parameters:: result The result to record.

Private Members

std::vector<OperationResult> history_: History of operations.

struct OperationResult

#include <calculator.hpp>

Structure to hold the result of a calculation.

Public Members

double value: The calculated value.

Operation operation: The operation that was performed.

std::string description: Human-readable description of the operation.

class ScientificCalculator : public calc::Calculator

#include <calculator.hpp>

An extended calculator with scientific functions.

This class inherits from Calculator and adds advanced mathematical operations like power and square root.

Public Functions

double power(double base, double exponent)

Calculate the power of a number.

Parameters:

base The base number.
exponent The exponent.

Returns:

base raised to the power of exponent.

double squareRoot(double value)

Calculate the square root of a number.

Parameters:: value The number to find the square root of.
Throws:: std::invalid_argument if value is negative.
Returns:: The square root of value.

namespace calc

The calculator namespace containing all calculator-related classes.

Typedefs

typedef std::vector<OperationResult> HistoryList: Type alias for the operation history container.

Enums

enum class Operation

Enumeration of supported arithmetic operations.

Values:

enumerator ADD: Addition operation.

enumerator SUBTRACT: Subtraction operation.

enumerator MULTIPLY: Multiplication operation.

enumerator DIVIDE: Division operation.

Functions

std::string formatNumber(double value, int precision = 2)

A helper function to format a number as a string.

Parameters:

value The number to format.
precision The number of decimal places.

Returns:

A formatted string representation.

namespace std: STL namespace.

file calculator.hpp

#include <stdexcept>

#include <string>

#include <vector>

A simple calculator library demonstrating Doxygen documentation.

This file contains the Calculator class and related utilities for performing basic arithmetic operations.

Defines

MAX_HISTORY_SIZE 1000: Maximum number of operations to store in history.

file calculator.cpp: #include calculator.hpp

#include <cmath>

#include <sstream>

#include <iomanip>

Implementation of the Calculator class.

dir include

dir src

Document Individual Classes

Or document specific classes with doxygenclass:

class Calculator

A class for performing basic arithmetic operations.

The Calculator class provides methods for addition, subtraction, multiplication, and division. It also maintains a history of operations performed.

Example usage:

calc::Calculator calc;
double result = calc.add(5.0, 3.0);
std::cout << "Result: " << result << std::endl;

Note

This is a thread-safe implementation.

Subclassed by calc::ScientificCalculator

Public Functions

Calculator()

Default constructor.

Initializes an empty calculator with no operation history.

virtual ~Calculator(): Destructor.

double add(double a, double b)

Add two numbers.

See also

subtract()

Parameters:

a The first operand.
b The second operand.

Returns:

The sum of a and b.

double subtract(double a, double b)

Subtract two numbers.

See also

add()

Parameters:

a The minuend.
b The subtrahend.

Returns:

The difference (a - b).

double multiply(double a, double b)

Multiply two numbers.

See also

divide()

Parameters:

a The first factor.
b The second factor.

Returns:

The product of a and b.

double divide(double a, double b)

Divide two numbers.

See also

multiply()

Warning

Division by zero will throw an exception.

Parameters:

a The dividend.
b The divisor.

Throws:

std::invalid_argument if b is zero.

Returns:

The quotient (a / b).

std::vector<OperationResult> getHistory() const

Get the history of all operations.

Returns:: A vector containing all operation results.

void clearHistory(): Clear the operation history.

size_t getOperationCount() const

Get the number of operations performed.

Returns:: The count of operations in history.

class ScientificCalculator : public calc::Calculator

An extended calculator with scientific functions.

This class inherits from Calculator and adds advanced mathematical operations like power and square root.

Public Functions

double power(double base, double exponent)

Calculate the power of a number.

Parameters:

base The base number.
exponent The exponent.

Returns:

base raised to the power of exponent.

double squareRoot(double value)

Calculate the square root of a number.

Parameters:: value The number to find the square root of.
Throws:: std::invalid_argument if value is negative.
Returns:: The square root of value.

Rust Example

This is an example of documenting Rust code using sphinxcontrib-rust integration.

Unlike the C++ and JavaScript examples below, the Rust pages are not written by hand. sphinx-rustdocgen reads each crate listed under [tool.yardang.sphinx-rust] and writes a page per module into the configured doc-dir, so the only thing to author is a toctree pointing at the result:

JavaScript Example

This is an example of documenting JavaScript code using sphinx-js integration.

Document Functions

Use js:autofunction to document individual functions:

static add(a, b)

Adds two numbers together.

Arguments:

a (number) The first number.
b (number) The second number.

Returns:

number The sum of a and b.

Example

const result = add(5, 3);
console.log(result); // 8

static subtract(a, b)

Subtracts the second number from the first.

Arguments:

a (number) The number to subtract from.
b (number) The number to subtract.

Returns:

number The difference of a and b.

Example

const result = subtract(10, 4);
console.log(result); // 6

static multiply(a, b)

Multiplies two numbers together.

Arguments:

a (number) The first number.
b (number) The second number.

Returns:

number The product of a and b.

Example

const result = multiply(4, 5);
console.log(result); // 20

static divide(a, b)

Divides the first number by the second.

Arguments:

a (number) The dividend.
b (number) The divisor.

Throws:

Error If b is zero.

Returns:

number The quotient of a divided by b.

Example

const result = divide(20, 4);
console.log(result); // 5

Document Classes

Use js:autoclass to document classes:

class Calculator()

A calculator that performs basic arithmetic operations and maintains history.

Creates a new Calculator instance.

Example

const calc = new Calculator();
const result = calc.calculate(10, 5, Operation.ADD);
console.log(result); // 15
console.log(calc.getHistory()); // [{...}]

Calculator.calculate(a, b, operation)

Performs a calculation with the given operands and operation.

Arguments:

a (number) The first operand.
b (number) The second operand.
operation (Operation) The operation to perform.

Throws:

Error If an invalid operation is provided.

Returns:

number The result of the calculation.

Example

const calc = new Calculator();
const sum = calc.calculate(5, 3, Operation.ADD); // 8
const diff = calc.calculate(10, 4, Operation.SUBTRACT); // 6

Calculator.clearHistory()

Clears the calculation history.

Returns:: void

Example

const calc = new Calculator();
calc.calculate(5, 3, Operation.ADD);
calc.clearHistory();
console.log(calc.getHistory().length); // 0

Calculator.getHistory()

Returns the history of all calculations.

Returns:: Array.<CalculationResult> An array of calculation results.

Example

const calc = new Calculator();
calc.calculate(5, 3, Operation.ADD);
calc.calculate(10, 2, Operation.MULTIPLY);
const history = calc.getHistory();
console.log(history.length); // 2

Calculator.getLastResult()

Gets the last calculation result.

Returns:: CalculationResult|null The last calculation result, or null if no calculations have been made.

class ScientificCalculator()

A scientific calculator with additional mathematical functions.

Example

const sci = new ScientificCalculator();
const result = sci.sin(Math.PI / 2);
console.log(result); // 1

ScientificCalculator.cos(radians)

Calculates the cosine of an angle in radians.

Arguments:

radians (number) The angle in radians.

Returns:

number The cosine of the angle.

ScientificCalculator.ln(n)

Calculates the natural logarithm of a number.

Arguments:

n (number) The number.

Throws:

Error If n is not positive.

Returns:

number The natural logarithm of n.

ScientificCalculator.log10(n)

Calculates the base-10 logarithm of a number.

Arguments:

n (number) The number.

Throws:

Error If n is not positive.

Returns:

number The base-10 logarithm of n.

ScientificCalculator.sin(radians)

Calculates the sine of an angle in radians.

Arguments:

radians (number) The angle in radians.

Returns:

number The sine of the angle.

ScientificCalculator.tan(radians)

Calculates the tangent of an angle in radians.

Arguments:

radians (number) The angle in radians.

Returns:

number The tangent of the angle.

Made with Sphinx and @pradyunsg's Furo

On this page

API Reference