Test Document

This is a test document. It is located at docs/test.md in the root directory and has both Chinese and English versions.

If you can see this document, it means the script successfully copied external Markdown documents from the project to the Sphinx source directory (docs/sphinx_doc/source/docs_index/) before the Sphinx build, enabling them to be built normally.

💡 Integration Rules:
The build script automatically scans all folders in the project root directory except outputs/, sphinx_doc/, and .github/, and copies Markdown files (.md) within them to the documentation build source directory.
Therefore, you can write Markdown documents in any unexcluded directories such as docs/, guides/, src/, etc.

As long as these files are correctly referenced through :glob: in docs/sphinx_doc/source/docs_index/index.rst (English) and index_ZH.rst (Chinese), they will typically appear in the final site like this document.

Example

====
Docs
====

Files in this project

.. toctree::
   :maxdepth: 2
   :glob:

   guides/*

.. toctree::
   :maxdepth: 2
   :glob:
   
   docs/*

docs/* will match all files copied from the docs/ directory, such as this document.

Media Asset References

Image Display

You can directly reference images, videos, and other media resources in your project using relative paths in Markdown documents:

![Example Image](https://github.com/datajuicer/data-juicer-sphinx/blob/main/docs/imgs/TEST.png)

Or:

<img src="imgs/TEST.png" width="70%" height="70%">

Asset Management Configuration

To ensure media resources are correctly built and displayed, you need to configure the extra_assets.yaml file to specify the paths where media resources are stored (relative to the project root). For example:

assets_dirs:
  - docs/imgs
  - resources

The build script will automatically copy resource files from these directories to the Sphinx build output directory, ensuring that the resources can be accessed normally in the final generated website.

Usage Instructions

1. Place resource files: Put image, video, and other media files in specified folders in the project root directory (such as imgs/)

2. Configure resource paths: Declare the directories containing resources in extra_assets.yaml

3. Reference resources: Use relative paths in Markdown, for example imgs/TEST.png

4. Local preview: When editing locally, relative paths should correctly point to resource files

5. Automatic mapping: The build script automatically handles path mapping, ensuring resources display correctly in the built website

With this configuration, you can preview both documents and images in your local editor while also ensuring that all media resources display correctly in the generated website.

Automatic Mapping of In-Repository Links

What are In-Repository Links?

In Markdown, you can reference other files in the code repository using relative paths, for example:

[View Script](https://github.com/datajuicer/data-juicer-sphinx/blob/main/docs/sphinx_doc/build_versions.py)
[Configuration File](https://github.com/datajuicer/data-juicer-sphinx/blob/main/docs/sphinx_doc/source/extra_assets.yaml)
[Related Documentation](docs/README.md)

These relative links in the form of ./xxx or path/to/file point to files inside the project repository.

Automatic Mapping

The build script automatically converts these in-repository relative links to GitHub repository links. First, make sure you have correctly set the following environment variables:

export PROJECT = "your-project-name"        # For example: data-juicer-hub
export REPO_OWNER = "your-repo-owner"       # For example: datajuicer

Original relative link:

[Script](https://github.com/datajuicer/data-juicer-sphinx/blob/main/docs/sphinx_doc/build_versions.py)

conf.py automatically calculates the file’s path relative to the project root and maps it to a GitHub link:

https://github.com/datajuicer/data-juicer-sphinx/blob/main/docs/sphinx_doc/build_versions.py

If multi-version builds are enabled, the links will also automatically point to the corresponding version branches.