pyDocusaurus: Convert your Python docstrings to Docusaurus Documentation

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

1. 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.
2. 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.
3. 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).

1. Install

Intall the latest released version of this package by using the PyPI source:

python -m pip install pydocusaurus

2. Usage

A simple usage is to use the CLI directly:

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

It allows customizations by adding CLI options. To find the details, review the documentation of this project or call

python -m pydocusaurus render-doc --help

pyDocusaurus can also be called by Python codes, for example:

from pydocusaurus import render_package_as_mdx
import any_package

pydocusaurus.render_package_as_mdx(
    pydocusaurus, out_dir=out_dir, package_info="username"
)

3. Documentation

Check the documentation to find more details about the examples and APIs.

https://cainmagi.github.io/pydocusaurus/

4. Contributing

See CONTRIBUTING.md 📖

5. Changelog

See Changelog.md 📖