API Reference¶

Python API¶

yardang.build¶

yardang.build.generate_docs_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, adjust_template: Callable = None)[source]¶

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.
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 to custom CSS file. Defaults to bundled custom.css.
custom_js – Path to custom JavaScript file. Defaults to bundled custom.js.
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:

FileNotFoundError – If custom_css or custom_js paths don’t exist.
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, adjust_template: Callable = 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.cli¶

yardang.cli.build(*, quiet: bool = False, debug: bool = False, pdb: bool = False, 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[Path] | None = None, use_autoapi: bool | None = None, custom_css: Path | None = None, custom_js: Path | None = None, config_base: str | None = 'tool.yardang', previous_versions: bool | None = False)[source]¶

yardang.cli.debug()[source]¶

yardang.cli.main()[source]¶

yardang.cli.wiki(*, quiet: bool = False, debug: bool = False, pdb: bool = False, 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[Path] | None = None, use_autoapi: bool | None = None, custom_css: Path | None = None, custom_js: Path | None = None, config_base: str | None = 'tool.yardang', previous_versions: bool | None = False, output_dir: str | None = None, skip_postprocess: bool = False)[source]¶

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¶

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

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 sphinx-rust integration.

Document a Crate¶

Use rust:crate to document an entire Rust crate:

Version: 0.1.0

pub mod calculator;[source]¶

Calculator Library¶

A simple calculator library demonstrating Rust documentation with sphinx-rust.

This crate provides basic arithmetic operations and a calculator struct that maintains a history of operations.

Example¶

use calculator::{Calculator, Operation};

let mut calc = Calculator::new();
let result = calc.calculate(5.0, 3.0, Operation::Add);
assert_eq!(result, 8.0);

Structs¶

`Calculator`	A calculator that performs basic arithmetic operations.
`ScientificCalculator`	A scientific calculator with additional mathematical functions.

Enums¶

CalculatorError

Errors that can occur during calculator operations.

Document Individual Items¶

Or document specific structs, enums, and functions:

pub struct Calculator(/* private fields */);¶

A calculator that performs basic arithmetic operations.

The Calculator struct maintains a history of all operations performed, allowing users to review previous calculations.

Examples¶

use calculator::Calculator;

let mut calc = Calculator::new();
let sum = calc.add(10.0, 5.0);
assert_eq!(sum, 15.0);

pub struct ScientificCalculator(/* private fields */);¶

A scientific calculator with additional mathematical functions.

Extends the basic [Calculator] with trigonometric, logarithmic, and other advanced mathematical operations.

pub struct CalculatorError { DivisionByZero(...), Overflow(...), }

Errors that can occur during calculator operations.

Variants¶

DivisionByZero:: Attempted to divide by zero.
Overflow:: The result overflowed.

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.