Mining/docs/README.md

Mining Documentation

Welcome to the documentation for the Mining project. This folder contains detailed information about the API, CLI, architecture, and development processes.

GitHub Pages Documentation

The full documentation is built with MkDocs and Material for MkDocs theme, and is available at:

https://snider.github.io/Mining/

Local Development

Prerequisites

• Python 3.x
• pip

Setup & Serve

1. Install dependencies:

pip install -r docs/requirements.txt

2. Serve the documentation locally:

mkdocs serve

The documentation will be available at http://127.0.0.1:8000/

Building

To build the static site:

mkdocs build

The built site will be in the site/ directory.

Legacy Documentation

• API Documentation: Detailed information about the RESTful API endpoints, request/response formats, and Swagger usage.
• CLI Documentation: A comprehensive guide to the Command Line Interface, including command descriptions and usage examples.
• Architecture Guide: An overview of the project's design, including the modular ManagerInterface, core packages, and data flow.
• Development Guide: Instructions for contributors on how to build, test, and release the project.

Project Structure

docs/
├── index.md                    # Home page
├── getting-started/            # Getting started guides
├── cli/                        # CLI command reference
├── api/                        # API documentation
├── dashboard/                  # Web dashboard docs
├── desktop/                    # Desktop application docs
├── development/                # Development guides
├── architecture/               # Architecture documentation
├── pools/                      # Pool integration docs
├── miners/                     # Miner-specific documentation
├── troubleshooting/            # Troubleshooting guides
├── stylesheets/
│   └── extra.css              # Custom CSS
└── requirements.txt           # Python dependencies

Writing Documentation

Markdown Extensions

This project uses PyMdown Extensions which provide additional features:

• Admonitions: !!! note, !!! warning, !!! tip, etc.
• Code blocks: Syntax highlighting with line numbers
• Tabs: Tabbed content blocks
• Task lists: GitHub-style checkboxes
• Emojis: :smile:
• Mermaid diagrams: Flow charts and diagrams

Example Admonition

!!! tip "Mining Tip"
    Make sure to check your GPU temperature regularly!

Example Code Block

```go title="main.go" linenums="1" hl_lines="2 3"
package main

import "fmt"

func main() {
    fmt.Println("Hello, Mining!")
}
```

Example Tabbed Content

=== "Linux"
    ```bash
    ./miner-ctrl serve
    ```

=== "Windows"
    ```powershell
    miner-ctrl.exe serve
    ```

=== "macOS"
    ```bash
    ./miner-ctrl serve
    ```

Contributing

When adding new documentation:

1. Create markdown files in the appropriate directory
2. Add the new page to the nav: section in mkdocs.yml
3. Follow the existing style and structure
4. Test locally with mkdocs serve
5. Submit a pull request

Deployment

Documentation is automatically deployed to GitHub Pages when changes are pushed to the main branch. The deployment is handled by the .github/workflows/docs.yml workflow.

Resources

• MkDocs Documentation
• Material for MkDocs
• PyMdown Extensions
• Mermaid Diagrams