documentation

A set of utility functions to generate documentation for the YouSleep project.

get_package_version(package_root_dir, require_tagged=False, latest_tagged=False, require_clean=False, append_commit_hash=False, ref=None)

Get the version of a git versioned package.

Returns the tag of the inspected commit with any leading v stripped, or its short hexsha when that commit carries no tag.

Parameters:

Name	Type	Description	Default
package_root_dir	str	The root directory of the package.	required
require_tagged	bool	If True, raises if the inspected commit is not tagged.	False
latest_tagged	bool	If True, returns the repository's newest tag and ignores which commit is inspected.	False
require_clean	bool	If True, raises if the repository has uncommitted changes.	False
append_commit_hash	bool	If True and the commit is untagged, returns the nearest preceding tag with the commit hash appended.	False
ref	str | None	Commit, tag or branch to inspect. Defaults to HEAD. Use it to ask what version a specific commit was released as — for example the commit a deployment tag pins in a submodule.	None

Returns:

Name	Type	Description
str	str	The version of the package.

Note

A shallow clone has no tags unless they were fetched explicitly, and this returns a short hexsha in that case. Fetch tags before calling it against a --depth 1 checkout.

mkdocs_gen_ref_pages(package, root, doc_prefix='reference')

Generate ref pages for the given package for mkdocs.

Note

This function generates reference pages for the given package. The reference pages are generated by recursively searching for all Python files in the package directory and generating a markdown file for each Python file. The markdown file contains the Python file's content with a YAML front matter block that specifies the title of the page.

Parameters:

Name	Type	Description	Default
package	str	The package name. E.g. "yousleep_common".	required
root	Path	The root path of the package repository. Must contain the package folder.	required
doc_prefix	str	The prefix to be added to the generated documentation files. Default is "reference".	'reference'

Returns:

Type	Description
None	None

Examples:

>>> mkdocs_gen_ref_pages("yousleep_common", Path(__file__).parent.parent)