docs src api

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)

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)

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]

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)

yardang.cli.debug()

yardang.cli.main()

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)

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')

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](api#calculatorclasscalc_1_1_calculator) [calc](#calculatornamespacecalc); double result = [calc](#calculatornamespacecalc).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: – 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: – 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 #include #include

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 #include #include

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](api#calculatorclasscalc_1_1_calculator) [calc](#calculatornamespacecalc); double result = [calc](#calculatornamespacecalc).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: – 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: – 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.

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.

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.

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.

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.

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.

Calculator.clearHistory()

Clears the calculation history.

• Returns: void

Calculator.getHistory()

Returns the history of all calculations.

• Returns: Array. – An array of calculation results.

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.

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.