Introduction

This package is inspired by Sphinx, which is usually thought of as the "official" solution for auto-generated Python documentation. According to Sphinx's documentation, the automatic generation can be described as:

Generate API documentation for Python, C++ and other software domains, manually or automatically from docstrings, ensuring your code documentation stays up-to-date with minimal effort.

——Sphinx

Overall, this package offers similar functionalities to Sphinx. It goes through the docstrings in the whole package and reorganizes them as an automatically generated API document. However, pyDocusaurus is not an extension of Sphinx, because

Sphinx is old. It was designed in an era when typing or type hints were not part of the Python standard library (STL). Therefore, Sphinx needs to infer the types from the docstrings. In modern Python code, this feature is redundant.
Sphinx is essentially proposed for reStructuredText (rst). Certainly, it supports Markdown with specific extensions. However, the Markdown features, especially those related to variable types, are not well integrated with the automatically generated API documents. Users may still suffer a lot of rst code in the generated document.
Limited by the old-school template, Sphinx does not produce a "modern" website.

Essentially, this package will produce a "patch" for a Docusaurus project. Like Sphinx, pyDocusaurus will go through the whole package and convert the docstring into a Docusaurus-compatible API document, while requiring minimal modifications when integrating the auto-generated document with an existing Docusaurus project (e.g., an existing tutorial site).

Usage

CLIs
Python

Run the following simple one-liner command to convert an existing package to a documentation.

python -m pydocusaurus render-doc <package-name> -o <out-dir> -u <user-name>

Check more details by using the help functionalities:

python -m pydocusaurus render-doc --help

Run the following script to convert an existing package to a documentation.

convert_docs.py
from pydocusaurus import render_package_as_mdx
import any_package

if __name__ == "__main__":
    render_package_as_mdx(
        any_package, out_dir="./docs-output", package_info="yourname"
    )

The output documentation files will be saved in ./docs-output. Here, the package_info is configured as the user name. For example, it supposes to be the GitHub user name if you are planning to put your documentation on GitHub.