Example scripts and usages

Here, we show several examples of extended usages.

1. Plain conversion

Nothing special, just like the examples shown in the introduction. This script can be found in

convert.py

CLIs

python -m pydocusaurus render-doc pydocusaurus -o ./docs-pydocusaurus -u cainmagi

Certainly, in the project folder, users can run

cd pydocusaurus
python -m examples.convert

Python

convert.py

from pydocusaurus import render_package_as_mdx
import pydocusaurus

if __name__ == "__main__":
    render_package_as_mdx(
        pydocusaurus, out_dir="./docs-pydocusaurus", package_info="cainmagi"
    )

2. Customized saver

Users can customize the behavior of saving the documents. The following scripts let all documentation files aggregated as a single YAML file. This script can be found in

custom_saver.py

CLIs

In the project folder, run

cd pydocusaurus
python -m examples.custom_saver

Python

custom_saver.py

import os
import json

from typing import Any

import yaml

import pydocusaurus

__all__ = ("render",)


class SaverSingleFile(pydocusaurus.renderer.package.SaverAbstract):
    """The saver that dumps all documentation files in a single file."""

    def __init__(self) -> None:
        """Initialization."""
        super().__init__()
        self.data: dict[str, str] = dict()

    def dump_yaml(self, out_path: str) -> None:
        """Dump the cached documentation files as a single YAML data file.

        Arguments
        ---------
        out_path: `str`
            The path where the document is saved. It is a YAML file.
        """
        os.makedirs(os.path.dirname(out_path), exist_ok=True)
        with open(out_path, "w", encoding="utf-8") as fobj:
            yaml.safe_dump(self.data, fobj, indent=2)

    def save_bytes(self, file_path: str | os.PathLike[str], data: bytes) -> None:
        """Save the binary data.

        Arguments
        ---------
        file_path: `str | PathLike[str]`
            The path to the output file.

        data: `bytes`
            The byte data to be saved.
        """
        self.data[str(file_path).strip()] = data.decode("utf-8")

    def save_text(self, file_path: str | os.PathLike[str], data: str) -> None:
        """Save the text file.

        Arguments
        ---------
        file_path: `str | PathLike[str]`
            The path to the output file.

        data: `str`
            The text data to be saved.
        """
        self.data[str(file_path).strip()] = data

    def save_data(self, file_path: str | os.PathLike[str], data: Any) -> None:
        """Save the structured data (such as json).

        Arguments
        ---------
        file_path: `str | PathLike[str]`
            The path to the output file.

        data: `Any`
            The structured data to be saved.
        """
        self.data[str(file_path).strip()] = json.dumps(data, indent=2)


def render() -> None:
    """Render the documentation of pydocusaurus."""
    cur_dir = os.path.dirname(__file__)
    out_dir = os.path.join(cur_dir, "docs-{0}".format(pydocusaurus.__name__))
    saver = SaverSingleFile()
    pydocusaurus.render_package_as_mdx(pydocusaurus, out_dir=out_dir, saver=saver)
    saver.dump_yaml(os.path.join(cur_dir, "docs-pydocusaurus-single.yml"))


if __name__ == "__main__":
    render()

3. Show the page of one entity

During debugging, we may need to know the performance of the rendered page for a specific entity. The following example shows how to print the page without converting the whole package.

This script can be found in

single_obj.py

CLIs

In the project folder, run

cd pydocusaurus
python -m examples.single_obj

Python

single_obj.py

import pydocusaurus

if __name__ == "__main__":
    print("Producing the documentation page: {0}".format(doc.slug))
    doc = pydocusaurus.render_obj(pydocusaurus.components.comprotocol.ProtocolComponent)
    if doc is None:
        print("Fail to produce the documentation page.")
        return
    print("")
    print(doc.render())