configuration

Configuration

Configuration for yardang is driven from the pyproject.toml, either via standard sections like project or from the dedicated tool.yardang section. Each option below corresponds to the Sphinx configuration.

Here is yardang’s own configuration, in pyproject.toml

[tool.yardang]
root = "docs/src/home.md"
cname = "yardang.python-templates.dev"
pages = [
    "docs/src/overview.md",
    "docs/src/installation.md",
    "docs/src/configuration.md",
]
use-autoapi = true

name

The project name is taken from the standard section, or from the cwd.

[project]
name = "your project name"

title

Same as name

module

The module title is taken from the name, replacing - with _, or from the cwd doing the same.

description

[project]
description = "your project description"

author

[project]
authors = "your project authors"

version

[project]
version = "0.1.0"

theme

Defaults to furo.

[tool.yardang]
theme = "furo"

theme

Defaults to furo.

[tool.yardang]
theme = "furo"

root

The root page to use, defaults to README.md.

[tool.yardang]
root = "docs/src/index.md"

cname

If set, will generate a CNAME file for GitHub Pages custom domains.

[tool.yardang]
cname = "yardang.python-templates.dev"

pages

Pages to include in the contents tree.

[tool.yardang]
pages = [
    "docs/src/overview.md",
    "docs/src/installation.md",
    "docs/src/configuration.md",
]

use_autoapi

Whether or not to use Sphinx AutoAPI. NOTE: it is recommended to manually autodoc your code.

[tool.yardang]
use-autoapi = true

Sphinx Options

[tool.yardang]
html_theme_options = {}
html_static_path = []
html_css_files = []
html_js_files = []
source_suffix = []
exclude_patterns = []
language = "en"
pygments_style = "sphinx"

Myst

[tool.yardang]
myst_enable_extensions = ["colon_fence"]
myst_fence_as_directive = ["mermaid"]

Myst-NB

[tool.yardang]
nb_execution_mode = "off"
nb_execution_excludepatterns = []

Notebooks can be included with:

```{eval-rst}
.. toctree::
  :maxdepth: 1

  ../notebooks/example

An example follows:

* [Example Notebook](../notebooks/example.md)

## [Autodoc Pydantic](https://autodoc-pydantic.readthedocs.io/en/stable/users/examples.html) arguments

[Configuration for Autodoc Pydantic](https://autodoc-pydantic.readthedocs.io/en/stable/users/configuration.html).

```toml
[tool.yardang]
autodoc_pydantic_model_show_config_summary = false
autodoc_pydantic_model_show_validator_summary = false
autodoc_pydantic_model_show_validator_members = false
autodoc_pydantic_field_list_validators = false
autodoc_pydantic_field_show_constraints = false
autodoc_pydantic_model_member_order = "bysource"
autodoc_pydantic_model_show_json = true
autodoc_pydantic_settings_show_json = false
autodoc_pydantic_model_show_field_summary = false

Mermaid

GitHub Admonitions

GitHub admonitions are automatically translated to sphinx.

NOTE

Note content

IMPORTANT

Important content

WARNING

Warning content