211 lines
4.2 KiB
Markdown
211 lines
4.2 KiB
Markdown
# OpenClaw Trading Documentation
|
|
|
|
This directory contains the Sphinx documentation for OpenClaw Trading.
|
|
|
|
## Building the Documentation
|
|
|
|
### Prerequisites
|
|
|
|
Install documentation dependencies:
|
|
|
|
```bash
|
|
pip install sphinx sphinx-rtd-theme
|
|
```
|
|
|
|
Or install with all dev dependencies:
|
|
|
|
```bash
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
### Build HTML Documentation
|
|
|
|
```bash
|
|
cd docs
|
|
make html
|
|
```
|
|
|
|
The built documentation will be in `build/html/`.
|
|
|
|
### Live Reload (for development)
|
|
|
|
```bash
|
|
make livehtml
|
|
```
|
|
|
|
This starts a local server that rebuilds documentation automatically when files change.
|
|
|
|
### Clean Build
|
|
|
|
```bash
|
|
make clean
|
|
make html
|
|
```
|
|
|
|
## Documentation Structure
|
|
|
|
```
|
|
source/
|
|
├── index.rst # Main documentation index
|
|
├── quickstart.rst # Quick start guide
|
|
├── installation.rst # Installation instructions
|
|
├── architecture.rst # System architecture overview
|
|
├── agents.rst # Agent documentation
|
|
├── workflow.rst # Workflow system documentation
|
|
├── factors.rst # Trading factors documentation
|
|
├── learning.rst # Learning system documentation
|
|
├── backtesting.rst # Backtesting system documentation
|
|
├── monitoring.rst # Monitoring and alerts documentation
|
|
├── configuration.rst # Configuration guide
|
|
├── deployment.rst # Deployment guide
|
|
├── examples.rst # Usage examples
|
|
├── api.rst # API reference (autogenerated)
|
|
├── conf.py # Sphinx configuration
|
|
├── _static/ # Static files (CSS, images)
|
|
└── _templates/ # HTML templates
|
|
```
|
|
|
|
## Writing Documentation
|
|
|
|
### reStructuredText Format
|
|
|
|
Documentation is written in reStructuredText (.rst) format.
|
|
|
|
Basic syntax:
|
|
|
|
```rst
|
|
Section Header
|
|
==============
|
|
|
|
Subsection
|
|
----------
|
|
|
|
This is a paragraph with **bold** and *italic* text.
|
|
|
|
- Bullet point 1
|
|
- Bullet point 2
|
|
|
|
#. Numbered item 1
|
|
#. Numbered item 2
|
|
|
|
Code blocks::
|
|
|
|
def hello():
|
|
print("Hello, World!")
|
|
|
|
Links:
|
|
|
|
- External: `Link text <https://example.com>`_
|
|
- Internal: :doc:`quickstart`
|
|
- Reference: :ref:`section-label`
|
|
```
|
|
|
|
### Code Examples
|
|
|
|
Include code examples with:
|
|
|
|
```rst
|
|
.. code-block:: python
|
|
|
|
from openclaw.core.economy import TradingEconomicTracker
|
|
|
|
tracker = TradingEconomicTracker("agent_001", 1000.0)
|
|
```
|
|
|
|
### Auto-generating API Docs
|
|
|
|
Use autodoc to generate API documentation from docstrings:
|
|
|
|
```rst
|
|
.. automodule:: openclaw.core.economy
|
|
:members:
|
|
:undoc-members:
|
|
:show-inheritance:
|
|
```
|
|
|
|
### Cross-References
|
|
|
|
Link between documents:
|
|
|
|
```rst
|
|
See the :doc:`quickstart` for a quick introduction.
|
|
|
|
See :doc:`/api` for API reference.
|
|
|
|
For more details, see the :ref:`configuration-section` section.
|
|
```
|
|
|
|
## Style Guidelines
|
|
|
|
1. **Line length**: Keep lines under 100 characters
|
|
2. **Headings**: Use sentence case
|
|
3. **Code**: Always specify the language for syntax highlighting
|
|
4. **Examples**: Include runnable code examples
|
|
5. **Links**: Use descriptive link text
|
|
6. **Images**: Place in `_static/` directory
|
|
7. **Formatting**: Use consistent indentation (3 spaces)
|
|
|
|
## Deploying Documentation
|
|
|
|
### GitHub Pages
|
|
|
|
Deploy to GitHub Pages:
|
|
|
|
```bash
|
|
make deploy
|
|
```
|
|
|
|
This requires:
|
|
|
|
- `ghp-import` installed: `pip install ghp-import`
|
|
- Push access to the repository
|
|
|
|
### Read the Docs
|
|
|
|
The documentation is automatically built and hosted on Read the Docs.
|
|
|
|
URL: https://openclaw-trading.readthedocs.io
|
|
|
|
### Custom Server
|
|
|
|
Build and copy to web server:
|
|
|
|
```bash
|
|
make html
|
|
rsync -avz build/html/ user@server:/var/www/docs/
|
|
```
|
|
|
|
## Testing Documentation
|
|
|
|
### Check for Broken Links
|
|
|
|
```bash
|
|
make linkcheck
|
|
```
|
|
|
|
### Check for Missing References
|
|
|
|
```bash
|
|
make html
|
|
# Check for warnings about undefined references
|
|
```
|
|
|
|
## Updating Documentation
|
|
|
|
When adding new features:
|
|
|
|
1. Update relevant `.rst` files
|
|
2. Add code examples
|
|
3. Update API reference
|
|
4. Test build with `make html`
|
|
5. Check for warnings/errors
|
|
6. Commit changes
|
|
|
|
## Help
|
|
|
|
For Sphinx documentation:
|
|
|
|
- Official docs: https://www.sphinx-doc.org/
|
|
- RST primer: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
|
|
- Autodoc extension: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
|