Render the documentation site

The following instructions show how to integrate the pyDocusaurus generated documentation files into the Docusaurus site. It covers the following topics:

Creating a fresh Docusaurus site;
Generating documentation with pyDocusaurus;
Integrating the generated files;
Updating an existing versioned documentation site.

1. Site preparation

Create an empty Docusaurus project by:

npx create-docusaurus@latest my-website classic --typescript --package-manager yarn

Then, enter the project folder, and install these extra dependencies:

cd my-website
yarn add @docusaurus/plugin-content-docs @docusaurus/theme-common \
         @iconify-icons/codicon @iconify-icons/mdi @iconify-icons/octicon \
         @iconify/react docusaurus-plugin-sass sass sass-loader \
         prism-react-renderer remark-math@6 rehype-katex@7

yarn add --dev @types/node
yarn install
yarn dlx @yarnpkg/sdks vscode

2. Generate documentation

Go to your Python package project folder. Suppose that you have the following folder structure:

Run pyDocusaurus by

CLIs
Python

python -m pydocusaurus render-doc my_package -o ./output_docs -u myname

convert_docs.py
from pydocusaurus import render_package_as_mdx
import my_package

if __name__ == "__main__":
    render_package_as_mdx(
        my_package, out_dir="./output_docs", package_info="myname"
    )

This produces:

These files form a patch that can be copied directly into a new Docusaurus site:

# Copy the pyDocusaurus outputs into the site
cp -rf ./output_docs/* /path/to/my-website

3. Modify the information

Then, you can modify:

docusaurus.config.ts: site metadata, themes, plugins
sidebars.ts: pyDocusaurus already generates a complete API sidebar. You need to customize the other parts such as the tutorial document sidebar.

You may also need to customize the index page of your documentation site. An example can be found here:

Index of flask-sqlalchemy-compat

4. Update existing documentation site.

In this case, you should not directly copy (overwrite) all files into your site because you may need to preserve your previous API documents.

Suppose that you need to update a new version of the documents. You may need to:

Follow the official guides first, especially for the following command:
```
yarn docusaurus docs:version 1.0.0
```
Use pydocusaurus to render the output documents.
Remove the entire ./docs/apis folder because the current API documents are delegated to pyDocusaurus now.

Copy new API documents:

cp -rf output_docs/docs/apis ./docs/apis

Merge the new sidebar.

Do not replace your entire sidebars.ts.

Only update the apis section:

const sidebars: SidebarsConfig = {
  // By default, Docusaurus generates a sidebar from the docs folder structure
  // tutorial: [{type: "autogenerated", dirName: "."}],

  tutorial: [
    "introduction",
    "tutorial/install",
    {...},
    "license",
  ],

  apis: [
    // Copy your new sidebar here.
  ]
}

Integrate the updated output_docs/src/env/variables.tsx into your project. You only need to add this part:

interface EnvVariables {
  ...
  sourceVersion: {
    "main": string;
    "v1.0.0": string;
    "v2.0.0": string;  // Added
    [key: string]: any;
  }
  sourceURIs: {
    "main": {[key: string]: string};
    "v1.0.0": {[key: string]: string};
    "v2.0.0": {[key: string]: string};  // Added
    [key: string]: any;
  }
  ...
}

const variables: EnvVariables = {
  repoURL: "...",
  rawURL: "...",
  sourceVersion: {
    "main": "main",
    "v1.0.0": "v1.0.0",
    "v2.0.0": "v2.0.0",  // the value is the branch/tag name.
  },
  sourceURIs: {
    "v2.0.0": {
      // Put your newly generated sourceURIs.main body here.
    }
    "v1.0.0": {
      ".": "./__init__.py",
      ...
    },
    "main": {
      ".": "./__init__.py",
      ...
    }
  },
};

This step tells the live rendering the line number of each entity in your source code. These automatically generated links will be used in the top bar of each API document page.

1. Site preparation​

2. Generate documentation​

3. Modify the information​

4. Update existing documentation site.​

1. Site preparation

2. Generate documentation

3. Modify the information

4. Update existing documentation site.