Integration guide for your extension
Implementation guides are the documentation you provide to guide users through the implementation of your extension in Agora projects. In the Extensions Marketplace, your extension has a detail page that contains a link to your implementation guides. The link leads users to the latest version of your documentation.
Your implementation guides must contain the following:
- Quickstart: A step-by-step procedure that explains how to integrate and use your extension in an Agora project.
- API reference: A detailed description of the APIs that users use to customize your extension.
To build your extension documentation, you do not have to start from scratch. This page shows how to use the template provided by Agora to write, output HTML for local testing using Sphinx, and host your documentation on a web server using Read the Docs.
To follow the procedure on this page, you must have:
- Python 3.7 or later, with
- A code editing tool, such as Visual Studio Code.
- A GitHub, BitBucket, or GitLab account, which is used to create a public repository to host your documentation.
Use the template to write
To use the template to write your documentation, take the following steps:
- Unzip the extension documentation template to a local folder.
- In your code editing tool, open the
_contentfolder and edit the following files:
quickstart.md: Explain how to integrate the features of your extension step by step. Use the template instructions as a reference.
api-reference.md: Provide detailed description of the APIs related to using your extension. Use the template instructions as a reference.
index.md: Provide your documentation repository URL and write a welcome page.
Output HTML for local testing
Before making your documentation publicly accessible, the best practice is to view and test it locally. This section describes how to generate an HTML output for your documentation using configurations in the template.
Set up the build environment
The template is configured to generate styled HTML from source files written in Markdown. To generate HTML output that is customized for your extension, take the following steps:
_content/conf.py, make the following changes:
- Fill in the
author, and github_doc_rootfields to add your project information.
html_faviconwith your logo and icon. You can either put the source image in the
_staticfolder or insert the URL to the image.
html_titleto the title of your documentation.
- Fill in the
In Terminal, run the following command line to install Sphinx:
In Terminal, run the following command line to install the packages for Markdown support:
In Terminal, run the following command line to install the HTML theme:
Output HTML locally
To generate an HTML output for local testing, take the following steps:
In Terminal, change the directory to the
_contentfolder and run the following command line:
If everything goes well, you see something like this:
build succeeded, 1 warning.
In your browser, open
_content/__build/html/index.htmlto see the welcome page of your documentation. In the left navigation panel, click Quickstart or API Reference to review your work.
To change the content on the HTML pages, edit the corresponding source file and save your edits. Then run
make htmlagain to review your change.
Repeat the previous step until you think your HTML pages are ready to be published.
Publish your documentation
To make your documentation publicly accessible through a URL, take the following steps:
- Create a public repository for your documentation folder (
extension-doc-templateif you have not renamed it).
- Import and build your documentation using Read the Docs, which assigns a URL for your documentation.
- If you need to update your documentation, edit the source files and push the commit to your repository. The update is automatically published in your documentation.
To ensure that users always get up-to-date content about your extension, provide your documentation URL to Agora before officially publishing your extension in the Gallery. For details, see Publish Your Extension.