We use Sphinx as the documentation tool and reStructuredText as the language. Sphinx primarily reads configurations from a Python script (conf.py), pulls documentation from comments in the code (via the autodoc extension), and organizes content through its table of contents hierarchy defined in .rst files.
git clone https://github.com/SylphAI-Inc/LightRAG.git
You can use either poetry or pip to install the necessary packages.
Use poetry:
All the packages are manged in the project's pyproject.toml file in the doc dependencies section. You can install all the necessary packages by running:
poetry install --with doc
Use pip:
Or you can use pip to install the necessary packages listed in requirements.txt:
pip install -r requirements.txt
cd docs
make htmlBuild with more options:
sphinx-build -b html source build -v
After building the documentation, you can use any browser to view it by opening the index.html file located in docs/build/html.
Some browsers restrict loading local resources like CSS for security reasons. In this case, try to use a local server to serve the file in the build/html directory. Run the following code:
cd docs/build/html
python -m http.server # Run this in your build/html directory
You will find the port shown in the terminal, e.g. Serving HTTP on :: port 8000 (http://[::]:8000/) .... In this case, you should open http://127.0.0.1:8000/ in your browser and you will see the documentation.
The docs/source/conf.py controls the configurations used by Sphinx to build the documentation, including the project-related information, sphinx extensions, templates configuration, html theme, patterns to exclude, language configuration, project path setup, etc.
The docs/source/index.rst is the root document for Sphinx-generated documentation("homepage" for the documentation site). It includes the toctree that defines the documentation hierarchical structure(sections/chapters). It also links to other .rst files that users can navigate through.
For example, in the index.rst, the :caption: Get Started corresponds to the section name of the documentation site. installation and introduction are the detailed pages.
What is LightRAG?
=================
LightRAG comes from the best of the AI research and engineering. Fundamentally, we ask ourselves: what kind of system that combines the best of research(such as LLM), engineering (such as 'jinja') to build the best applications? We are not a framework. We do not want you to directly install the package. We want you to carefully decide to take modules and structures from here to build your own library and applications. This is a cookbook organized uniquely for easy understanding: you can read the 1000 lines of code to see a typical RAG end-to-end without jumping between files and going through multi-level class inheritance. If we build our system expanding from light_rag.py, we as a community will share the same RAG languages, and share other building blocks and use cases easily without depending on a complex framework.
.. toctree::
:glob:
:maxdepth: 1
:caption: Get Started
get_started/installation
get_started/introduction
Existing sections include:
get_started/: Includes installation and LightRAG introduction
tutorials/: Includes sample code and instructions
apis/: All the source-code-related documents will be included in this directory
resources/: Include all the LightRAG-relevant resources.
Most of the documentation updates should be written as comments/doc-strings in your source code, which will be automatically converted to docs. Do manual editing when you add instructions to use your code, adjust the layout, etc.
The existing documentation is a combination of automatic generation and human editing.
The autodoc extension in conf.py combined with .. automodule:: in the .rst files makes it easy to update documents from the source code.
If you update the existing source code, you only need to run:
cd docs
make clean
make htmlAnd your documentation will be updated.
If you add new modules or code to the project, sphinx has a command to automatically generate the code docs.
sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN …]Note:
If your new module is a folder, it should contain a __init__.py file.
Remember to exclude the code that you don’t need in the [EXCLUDE_PATTERN …], otherwise Sphinx will compile them all.
Example:
Located in the root directory, run:
sphinx-apidoc -o docs/source/tutorials ./use_cases **test**(test is to exclude the files containing test in the filename)
You will find a modules.rst and a use_cases.rst in the docs/source/tutorials. The use_cases.rst contains all the packages included in your ./use_cases.
Then you should add the link to the index.rst to show your source code and docs in the documentation. Find docs/source/index.rst and add the new section:
.. toctree::
:glob:
:maxdepth: 1
:caption: Use Cases
tutorials/use_casesThen run:
cd docs
make clean
make htmlAnd you will be able to find the newly added use_cases module.
If you want to add any written files such as README.md to the documentation, there is an easy way to transform the files to .rst files using Pandoc.
-
First, install Pandoc with Homebrew:
brew install pandoc -
Then run
pandoc -s <input .md file> -o <path/to/target_rst_file>. For example, in the root directory runpandoc -s README.md -o docs/source/get_started/introduction.rst.This command will take content fromREADME.mdand create anintroduction.rstfile in the specified directory.
After editing, run
cd docs
make clean
make htmlRemember to exclude any unnecessary files in .gitignore. Please don’t commit files in docs/build. We can dynamically build local documentation with the make files and source/.
Please push your updates to the GitHub repo.
The structure of the code base and the docs:
LightRAG/
├── docs/
│ ├── apis/
│ │ ├── core/
│ │ │ ├── core.module1.rst
│ │ │ ├── core.module2.rst
│ │ ├── components/
│ │ │ ├── components.module1.rst
│ │ │ ├── components.module2.rst
│ ├── build/
│ │ ├── html/
│ │ │ ├── _static/
│ │ │ ├── _templates/
│ │ │ ├── index.html
│ │ │ ├── core/
│ │ │ │ ├── core.module1.html
│ │ │ │ ├── core.module2.html
│ │ │ ├── components/
│ │ │ │ ├── components.module1.html
│ │ │ │ ├── components.module2.html
│ ├── _static/
│ ├── _templates/
│ ├── conf.py
│ ├── index.rst
│ ├── Makefile
├── core/
│ ├── __init__.py
│ ├── module1.py
│ ├── module2.py
├── components/
│ ├── __init__.py
│ ├── module1.py
│ ├── module2.py