doc_style.hpp File Reference

Docstring styles shared by welder's Python backends. More...

#include <span>
#include <string>
#include <string_view>
#include <welder/doc.hpp>

Include dependency graph for doc_style.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	welder::rods::python::google_style
	Google-style docstring assembly (the default). More...
struct	welder::rods::python::numpy_style
	NumPy-style docstring assembly (numpydoc). More...
struct	welder::rods::python::sphinx_style
	Sphinx-style docstring assembly (reStructuredText field lists). More...

Namespaces
namespace	welder
namespace	welder::rods
namespace	welder::rods::python
namespace	welder::rods::python::detail

Functions
constexpr void	welder::rods::python::detail::append_indented (std::string &out, const char *text, std::string_view indent)
	Append text to out, indenting every continuation line by indent so a multiline param/returns doc stays visually under its block (docs often carry examples spanning lines).
constexpr void	welder::rods::python::detail::blank_line (std::string &out)
	Separate a new block from preceding content in out by exactly one blank line, whether or not that content already ended in a newline (a summary does not; a section body typically does).
constexpr bool	welder::rods::python::detail::any_param_doc (const ::welder::detail::function_doc &d)
	Whether d has at least one documented parameter (so a params block is worth opening).

Detailed Description

Docstring styles shared by welder's Python backends.

The language-agnostic documentation layer (<welder/doc.hpp>) reads the [[=welder::doc(...)]] / returns / parameter annotations off a reflected function and hands the raw pieces (welder::detail::function_doc) to a style — a type satisfying welder::doc_style — which folds them into one docstring. This header holds the styles the Python backends (pybind11, nanobind, …) share, so neither re-derives how a Python docstring reads. A backend selects one via its DocStyle template parameter (welder::rods::pybind11::basic_rod<Style>), which it passes to welder::function_docstring; the default is welder::rods::python::google_style.

Three conventions are provided, matching the three docstring dialects the Python ecosystem's doc tools understand:

• welder::rods::python::google_style — Google (Args: / Returns: blocks; Napoleon-parsed);
• welder::rods::python::numpy_style — NumPy / numpydoc (underlined Parameters / Returns sections; also Napoleon-parsed);
• welder::rods::python::sphinx_style — Sphinx / reStructuredText (:param name: / :returns: field lists, the format sphinx-autodoc emits natively).

Every style's format is constexpr: it is a plain std::string assembly, unit-testable by static_assert the same way welder::cleandoc is, and usable in any future compile-time context. That is also why the assembly is hand-rolled rather than written with std::format — std::format is not constexpr in the standard library (as of gcc-16), so a constexpr docstring builder cannot call it.

Requires the welder vocabulary first (#include <welder/vocabulary.hpp>), like the rest of the reflection layer.

Definition in file doc_style.hpp.