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 = ["amsmath", "colon_fence", "dollarmath", "html_image"]
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

Autodoc Pydantic arguments¶

Configuration for Autodoc Pydantic.

[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¶

        graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;

        %%{init: {"flowchart": {"defaultRenderer": "elk"}} }%%

graph TD
  A[\Replenish Value Add stock/] --->C
  B(Order product with Value Add) --->C
  C{Frequent process?} --->|Yes|D
  C --->|No|F
  D{New template?} --->|Yes|E
  D --->|No|G
  E(Create work order template) --->G
  F(Create work order) --->H
  G(Copy template to work order) --->I
  H(Add materials to work order processes) --->J
  I(Adjust material quantities) --->J
  J(Monitor work orders) --->K
  K{Material quantities in stock?} --->|No|L
  K --->|Yes|M
  L(Procure materials) --->M
  M(Change status to In Progress) --->N
  N{External Vendor to perform step?} --->|Yes|O
  N --->|No|P
  O(Add vendor costs) --->Q
  P[\Perform work order step/] --->R
  Q([Ship materials to Vendor]) --->S --->X
  R{Additional processing required?} --->|Yes|N
  R--->|No|T
  S[\Perform work order step/] --->U
  T(Receive final stock) --->V
  U(Receive product from vendor) --->W
  V(Ship product on order) --->Y
  W{Partial quantity received?} --->|Yes|X
  W --->|No|Z
  X[Create work order backorder] ---> J
  Y(Change status to complete) --->AA
  Z(Pay vendor invoice) --->R
  AA([Finish])

        zenuml
    title Demo
    Alice->John: Hello John, how are you?
    John->Alice: Great!
    Alice->John: See you later!

        mindmap
  root((mindmap))
    Origins
      Long history
      ::icon(fa fa-book)
      Popularisation
        British popular psychology author Tony Buzan
    Research
      On effectiveness<br/>and features
      On Automatic creation
        Uses
            Creative techniques
            Strategic planning
            Argument mapping
    Tools
      Pen and paper
      Mermaid

GitHub Admonitions¶

GitHub admonitions are automatically translated to sphinx.

Note

Note markdown content

Tip

Tip content

Important

Important content

Warning

Warning content

Caution

Caution content

Breathe/Doxygen Integration¶

Yardang provides integration with Breathe for documenting C/C++ code using Doxygen. To use this feature, install yardang with the breathe extra:

pip install yardang[breathe]

All breathe configuration is under [tool.yardang.breathe].

`projects`¶

A dictionary mapping project names to their Doxygen XML output directories.

[tool.yardang.breathe]
projects = { myproject = "docs/doxygen/xml", another = "path/to/xml" }

`default-project`¶

The default project to use when no project is specified in breathe directives.

[tool.yardang.breathe]
default-project = "myproject"

`domain-by-extension`¶

Map file extensions to Sphinx domains.

[tool.yardang.breathe]
domain-by-extension = { "hpp" = "cpp", "h" = "cpp", "py" = "py" }

`domain-by-file-pattern`¶

Map file patterns to Sphinx domains.

[tool.yardang.breathe]
domain-by-file-pattern = { "*.hpp" = "cpp" }

`projects-source`¶

Configure source files for automatic Doxygen XML generation.

[tool.yardang.breathe]
projects-source = { auto = ["src", ["file1.hpp", "file2.hpp"]] }

`build-directory`¶

The directory where Doxygen XML is built.

[tool.yardang.breathe]
build-directory = "build/doxygen"

`default-members`¶

Default member visibility for doxygenclass directives.

[tool.yardang.breathe]
default-members = ["members", "protected-members", "private-members"]

`show-define-initializer`¶

Show the initializer value for #define macros.

[tool.yardang.breathe]
show-define-initializer = true

`show-enumvalue-initializer`¶

Show the initializer value for enum values.

[tool.yardang.breathe]
show-enumvalue-initializer = true

`show-include`¶

Show the #include directive for documented entities.

[tool.yardang.breathe]
show-include = true

`implementation-filename-extensions`¶

List of file extensions considered as implementation files.

[tool.yardang.breathe]
implementation-filename-extensions = [".c", ".cc", ".cpp"]

`doxygen-config-options`¶

Additional Doxygen configuration options for auto-generated XML.

[tool.yardang.breathe]
doxygen-config-options = { EXTRACT_ALL = "YES", QUIET = "YES" }

`doxygen-aliases`¶

Doxygen aliases for custom commands.

[tool.yardang.breathe]
doxygen-aliases = { "myalias" = "Custom documentation text" }

`use-project-refids`¶

Use project-qualified reference IDs to avoid conflicts.

[tool.yardang.breathe]
use-project-refids = true

`order-parameters-first`¶

Order function parameters before other members in documentation.

[tool.yardang.breathe]
order-parameters-first = true

`separate-member-pages`¶

Generate separate pages for each class member.

[tool.yardang.breathe]
separate-member-pages = false

Complete Example¶

Here’s a complete example configuration for a C++ project:

[tool.yardang]
title = "My C++ Library"
root = "docs/index.md"
pages = ["docs/api.md", "docs/examples.md"]
use-autoapi = false

[tool.yardang.breathe]
projects = { mylib = "docs/doxygen/xml" }
default-project = "mylib"
domain-by-extension = { "hpp" = "cpp", "cpp" = "cpp", "h" = "cpp" }
show-define-initializer = true
show-enumvalue-initializer = true
show-include = true
use-project-refids = true

Then in your documentation files, you can use breathe directives:

# API Reference

## MyClass

\`\`\`{doxygenclass} MyNamespace::MyClass
:members:
:protected-members:
\`\`\`

## Functions

\`\`\`{doxygenfunction} MyNamespace::myFunction
\`\`\`

Sphinx-Rust Integration¶

Yardang provides integration with sphinx-rust for documenting Rust code. To use this feature, install yardang with the sphinx-rust extra:

pip install yardang[sphinx-rust]

All sphinx-rust configuration is under [tool.yardang.sphinx-rust].

`crates`¶

A list of paths to Rust crates to document.

[tool.yardang.sphinx-rust]
crates = [
    "path/to/crate1",
    "path/to/crate2",
]

`doc-formats`¶

A dictionary mapping crate names to their docstring format. Valid values are "restructuredtext" (default) or "myst-nb" (for markdown docstrings).

[tool.yardang.sphinx-rust]
doc-formats = { mycrate = "myst-nb" }

Note: When using myst_nb as your Sphinx parser (which yardang uses by default), use "myst-nb" instead of "markdown" for markdown docstrings.

`viewcode`¶

Enable links to the source code for documented items. Defaults to true.

[tool.yardang.sphinx-rust]
viewcode = true

Complete Example¶

Here’s a complete example configuration for a Rust project:

[tool.yardang]
title = "My Rust Library"
root = "docs/index.md"
pages = ["docs/api.md", "docs/examples.md"]
use-autoapi = false

[tool.yardang.sphinx-rust]
crates = [
    "crates/mylib",
    "crates/mylib-utils",
]
doc-formats = { mylib = "myst-nb", "mylib-utils" = "restructuredtext" }
viewcode = true

Then in your documentation files, you can use sphinx-rust directives:

# API Reference

## Document a Crate

\`\`\`{eval-rst}
.. rust:crate:: mylib

\`\`\`

## Document Individual Items

\`\`\`{eval-rst}
.. rust:struct:: mylib::MyStruct

\`\`\`

\`\`\`{eval-rst}
.. rust:enum:: mylib::MyEnum

\`\`\`

\`\`\`{eval-rst}
.. rust:function:: mylib::my_function

\`\`\`

Sphinx-JS Integration¶

Yardang provides integration with sphinx-js for documenting JavaScript and TypeScript code. To use this feature, you also need JSDoc or TypeDoc installed:

# For JavaScript projects
npm install jsdoc

# For TypeScript projects
npm install typedoc

All sphinx-js configuration is under [tool.yardang.sphinx-js].

`js-source-path`¶

A list of directories containing your JS/TS source files, relative to the project root. This is required to enable sphinx-js.

[tool.yardang.sphinx-js]
js-source-path = ["src", "lib"]

Or as a single path:

[tool.yardang.sphinx-js]
js-source-path = "src"

`js-language`¶

The language of your source files. Use "javascript" (default) or "typescript".

[tool.yardang.sphinx-js]
js-language = "typescript"

`root-for-relative-js-paths`¶

The root directory for resolving relative JS entity paths. Required if you have multiple js-source-path entries.

[tool.yardang.sphinx-js]
root-for-relative-js-paths = "src"

`jsdoc-config-path`¶

Path to a JSDoc configuration file.

[tool.yardang.sphinx-js]
jsdoc-config-path = "jsdoc.json"

`jsdoc-tsconfig-path`¶

Path to a TypeScript configuration file (for TypeDoc).

[tool.yardang.sphinx-js]
jsdoc-tsconfig-path = "tsconfig.json"

`ts-type-bold`¶

Make TypeScript types bold in the output. Defaults to false.

[tool.yardang.sphinx-js]
ts-type-bold = true

Complete Example¶

Here’s a complete example configuration for a TypeScript project:

[tool.yardang]
title = "My TypeScript Library"
root = "docs/index.md"
pages = ["docs/api.md", "docs/examples.md"]
use-autoapi = false

[tool.yardang.sphinx-js]
js-language = "typescript"
js-source-path = ["src"]
jsdoc-tsconfig-path = "tsconfig.json"
ts-type-bold = true

Then in your documentation files, you can use sphinx-js directives:

# API Reference

## Functions

\`\`\`{js:autofunction} myFunction
\`\`\`

## Classes

\`\`\`{js:autoclass} MyClass
:members:
\`\`\`

## Modules

\`\`\`{js:automodule} myModule
\`\`\`

GitHub Wiki Integration¶

Yardang can generate GitHub Wiki compatible markdown documentation using sphinx-markdown-builder. This allows you to publish your documentation to a GitHub Wiki in addition to (or instead of) a static HTML site.

To generate wiki output, use the yardang wiki command instead of yardang build.

Wiki output is configured in the [tool.yardang.wiki] section:

[tool.yardang.wiki]
enabled = true
output-dir = "docs/wiki"
generate-sidebar = true
generate-footer = true
fix-links = true
footer-docs-url = "https://your-project.dev"
footer-repo-url = "https://github.com/your-org/your-project"
markdown-flavor = "github"

`enabled`¶

Enable the markdown builder extension. Must be true to use yardang wiki. Defaults to false.

[tool.yardang.wiki]
enabled = true

`output-dir`¶

Output directory for the generated markdown files. Defaults to "docs/wiki".

[tool.yardang.wiki]
output-dir = "docs/wiki"

`fix-links`¶

Fix internal markdown links for GitHub Wiki compatibility. Defaults to true.

[tool.yardang.wiki]
fix-links = true

`markdown-flavor`¶

Markdown flavor to use. Set to "github" for GitHub-flavored markdown. Defaults to "github".

[tool.yardang.wiki]
markdown-flavor = "github"

`markdown-anchor-sections`¶

Add anchors before each section. Defaults to true.

[tool.yardang.wiki]
markdown-anchor-sections = true

`markdown-anchor-signatures`¶

Add anchors before each function/class signature. Defaults to true.

[tool.yardang.wiki]
markdown-anchor-signatures = true

`markdown-bullet`¶

Bullet character to use for lists. Defaults to "-".

[tool.yardang.wiki]
markdown-bullet = "-"

Complete Example¶

[tool.yardang]
title = "My Project"
root = "docs/index.md"
pages = ["docs/overview.md", "docs/api.md"]

[tool.yardang.wiki]
enabled = true
output-dir = "docs/wiki"
generate-sidebar = true
generate-footer = true
footer-docs-url = "https://myproject.dev"
footer-repo-url = "https://github.com/myorg/myproject"
markdown-flavor = "github"

Usage¶

Generate GitHub Wiki output:

yardang wiki

The output will be in the docs/wiki/ directory (or the configured output directory). To publish to your GitHub Wiki:

# Clone your wiki repository
git clone https://github.com/YOUR-ORG/YOUR-REPO.wiki.git

# Copy the generated markdown files
cp -r docs/wiki/* YOUR-REPO.wiki/

# Commit and push
cd YOUR-REPO.wiki
git add .
git commit -m "Update wiki documentation"
git push

The generated wiki includes:

Home.md - The main landing page (converted from index.md)
_Sidebar.md - Navigation sidebar with links to all pages
_Footer.md - Footer with links to documentation and repository
All documentation pages converted to GitHub-flavored markdown

Configuration¶

name¶

title¶

module¶

description¶

author¶

version¶

theme¶

theme¶

root¶

cname¶

pages¶

use_autoapi¶

Sphinx Options¶

Myst¶

Myst-NB¶

Autodoc Pydantic arguments¶

Mermaid¶

GitHub Admonitions¶

Breathe/Doxygen Integration¶

projects¶

default-project¶

domain-by-extension¶

domain-by-file-pattern¶

projects-source¶

build-directory¶

default-members¶

show-define-initializer¶

show-enumvalue-initializer¶

show-include¶

implementation-filename-extensions¶

doxygen-config-options¶

doxygen-aliases¶

use-project-refids¶

order-parameters-first¶

separate-member-pages¶

Complete Example¶

Sphinx-Rust Integration¶

crates¶

doc-formats¶

viewcode¶

Complete Example¶

Sphinx-JS Integration¶

js-source-path¶

js-language¶

root-for-relative-js-paths¶

jsdoc-config-path¶

jsdoc-tsconfig-path¶

ts-type-bold¶

Complete Example¶

GitHub Wiki Integration¶

enabled¶

output-dir¶

generate-sidebar¶

generate-footer¶

fix-links¶

footer-docs-url¶

footer-repo-url¶

markdown-flavor¶

markdown-anchor-sections¶

markdown-anchor-signatures¶

markdown-bullet¶

Complete Example¶

Usage¶

`name`¶

`title`¶

`module`¶

`description`¶

`author`¶

`version`¶

`theme`¶

`theme`¶

`root`¶

`cname`¶

`pages`¶

`use_autoapi`¶

Myst ¶

Myst-NB ¶

`projects`¶

`default-project`¶

`domain-by-extension`¶

`domain-by-file-pattern`¶

`projects-source`¶

`build-directory`¶

`default-members`¶

`show-define-initializer`¶

`show-enumvalue-initializer`¶

`show-include`¶

`implementation-filename-extensions`¶

`doxygen-config-options`¶

`doxygen-aliases`¶

`use-project-refids`¶

`order-parameters-first`¶

`separate-member-pages`¶

`crates`¶

`doc-formats`¶

`viewcode`¶

`js-source-path`¶

`js-language`¶

`root-for-relative-js-paths`¶

`jsdoc-config-path`¶

`jsdoc-tsconfig-path`¶

`ts-type-bold`¶

`enabled`¶

`output-dir`¶

`generate-sidebar`¶

`generate-footer`¶

`fix-links`¶

`footer-docs-url`¶

`footer-repo-url`¶

`markdown-flavor`¶

`markdown-anchor-sections`¶

`markdown-anchor-signatures`¶

`markdown-bullet`¶