-
Notifications
You must be signed in to change notification settings - Fork 1
docs src 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 The project name is taken from the standard section, or from the cwd.
[project] name = "your project name" Same as name
The module title is taken from the name, replacing - with _, or from the cwd doing the same.
[project] description = "your project description" [project] authors = "your project authors" [project] version = "0.1.0" Defaults to furo.
[tool.yardang] theme = "furo" Defaults to furo.
[tool.yardang] theme = "furo" The root page to use, defaults to README.md.
[tool.yardang] root = "docs/src/index.md" If set, will generate a CNAME file for GitHub Pages custom domains.
[tool.yardang] cname = "yardang.python-templates.dev" Pages to include in the contents tree.
[tool.yardang] pages = [ "docs/src/overview.md", "docs/src/installation.md", "docs/src/configuration.md", ] Whether or not to use Sphinx AutoAPI. NOTE: it is recommended to manually autodoc your code.
[tool.yardang] use-autoapi = true [tool.yardang] html_theme_options = {} html_static_path = [] html_css_files = [] html_js_files = [] source_suffix = [] exclude_patterns = [] language = "en" pygments_style = "sphinx" [tool.yardang] myst_enable_extensions = ["amsmath", "colon_fence", "dollarmath", "html_image"] myst_fence_as_directive = ["mermaid"] [tool.yardang] nb_execution_mode = "off" nb_execution_excludepatterns = [] Notebooks can be included with:
```{eval-rst} .. toctree:: :maxdepth: 1 ../notebooks/example ```
An example follows:
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 GitHub admonitions are automatically translated to sphinx.
Note markdown content
Important content
Warning content
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].
A dictionary mapping project names to their Doxygen XML output directories.
[tool.yardang.breathe] projects = { myproject = "docs/doxygen/xml", another = "path/to/xml" } The default project to use when no project is specified in breathe directives.
[tool.yardang.breathe] default-project = "myproject" Map file extensions to Sphinx domains.
[tool.yardang.breathe] domain-by-extension = { "hpp" = "cpp", "h" = "cpp", "py" = "py" } Map file patterns to Sphinx domains.
[tool.yardang.breathe] domain-by-file-pattern = { "*.hpp" = "cpp" } Configure source files for automatic Doxygen XML generation.
[tool.yardang.breathe] projects-source = { auto = ["src", ["file1.hpp", "file2.hpp"]] } The directory where Doxygen XML is built.
[tool.yardang.breathe] build-directory = "build/doxygen" Default member visibility for doxygenclass directives.
[tool.yardang.breathe] default-members = ["members", "protected-members", "private-members"] Show the initializer value for #define macros.
[tool.yardang.breathe] show-define-initializer = true Show the initializer value for enum values.
[tool.yardang.breathe] show-enumvalue-initializer = true Show the #include directive for documented entities.
[tool.yardang.breathe] show-include = true List of file extensions considered as implementation files.
[tool.yardang.breathe] implementation-filename-extensions = [".c", ".cc", ".cpp"] Additional Doxygen configuration options for auto-generated XML.
[tool.yardang.breathe] doxygen-config-options = { EXTRACT_ALL = "YES", QUIET = "YES" } Doxygen aliases for custom commands.
[tool.yardang.breathe] doxygen-aliases = { "myalias" = "Custom documentation text" } Use project-qualified reference IDs to avoid conflicts.
[tool.yardang.breathe] use-project-refids = true Order function parameters before other members in documentation.
[tool.yardang.breathe] order-parameters-first = true Generate separate pages for each class member.
[tool.yardang.breathe] separate-member-pages = false 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 \`\`\` 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].
A list of paths to Rust crates to document.
[tool.yardang.sphinx-rust] crates = [ "path/to/crate1", "path/to/crate2", ] 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.
Enable links to the source code for documented items. Defaults to true.
[tool.yardang.sphinx-rust] viewcode = true 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 \`\`\` 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].
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" The language of your source files. Use "javascript" (default) or "typescript".
[tool.yardang.sphinx-js] js-language = "typescript" 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" Path to a JSDoc configuration file.
[tool.yardang.sphinx-js] jsdoc-config-path = "jsdoc.json" Path to a TypeScript configuration file (for TypeDoc).
[tool.yardang.sphinx-js] jsdoc-tsconfig-path = "tsconfig.json" Make TypeScript types bold in the output. Defaults to false.
[tool.yardang.sphinx-js] ts-type-bold = true 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 \`\`\` 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" Enable the markdown builder extension. Must be true to use yardang wiki. Defaults to false.
[tool.yardang.wiki] enabled = true Output directory for the generated markdown files. Defaults to "docs/wiki".
[tool.yardang.wiki] output-dir = "docs/wiki" Generate a _Sidebar.md file for wiki navigation. Defaults to true.
[tool.yardang.wiki] generate-sidebar = true Generate a _Footer.md file with links to docs and repo. Defaults to true.
[tool.yardang.wiki] generate-footer = true Fix internal markdown links for GitHub Wiki compatibility. Defaults to true.
[tool.yardang.wiki] fix-links = true URL to the full documentation site (for the footer).
[tool.yardang.wiki] footer-docs-url = "https://your-project.dev" URL to the repository (for the footer).
[tool.yardang.wiki] footer-repo-url = "https://github.com/your-org/your-project" Markdown flavor to use. Set to "github" for GitHub-flavored markdown. Defaults to "github".
[tool.yardang.wiki] markdown-flavor = "github" Add anchors before each section. Defaults to true.
[tool.yardang.wiki] markdown-anchor-sections = true Add anchors before each function/class signature. Defaults to true.
[tool.yardang.wiki] markdown-anchor-signatures = true Bullet character to use for lists. Defaults to "-".
[tool.yardang.wiki] markdown-bullet = "-" [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" 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
- Home
- Overview
- Installation
- Configuration
- Api
- Contributor Covenant Code of Conduct
- .Github Issue Template Bug Report
- .Github Issue Template Feature Request
- yardang
- Api Crates Calculator Code Calculator
- Enum calculator::CalculatorError
- Enums
- Struct calculator::Calculator
- Struct calculator::ScientificCalculator
- Structs
- Crate calculator
- Example Notebook
- API Reference
- Configuration
- Docs Src Home
- Installation
- Overview
- Calculator C++ API Documentation
- JavaScript Calculator Example
- Calculator Library (Rust)