# 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