Documentation Guide

Documentation Guide#

This guide covers everything you need to know about building, previewing, and contributing to the UVFlow documentation.

Overview#

The UVFlow documentation is built using Sphinx with the following features:

  • Markdown support via MyST Parser

  • API documentation auto-generated from Python docstrings

  • Multi-version support for different releases

  • Automatic deployment to GitHub Pages

  • Modern theme with search and navigation

Quick Start#

Prerequisites#

  • Python 3.8+ installed on your system

  • Git for version control

  • Text editor or IDE for editing documentation

1. Clone the Repository#

git clone https://github.com/CGCookie/uvflow.git
cd uvflow

2. Set Up Documentation Environment#

Windows:

setup-sphinx-venv.bat

Manual setup (all platforms):

cd docs
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

3. Build Documentation#

Windows:

sphinx_build_docs.bat

Manual build:

# Activate virtual environment first
call docs\venv\Scripts\activate  # Windows
# source docs/venv/bin/activate    # Linux/Mac

# Build documentation
sphinx-build docs docs/_build/html

4. Preview Documentation#

Open docs/_build/html/index.html in your web browser to preview the documentation locally.

Quick preview (Python built-in server):

cd docs/_build/html
python -m http.server 8000

Then visit http://localhost:8000 in your browser.

Documentation Structure#

docs/
├── _build/                 # Generated documentation (git-ignored)
├── _static/               # Static assets (CSS, images, etc.)
├── _templates/            # Custom Sphinx templates
├── api/                   # Auto-generated API documentation
├── developer_guide/       # Developer documentation
│   ├── addon_utils/       # addon_utils system documentation
│   └── getting_started/   # Getting started guides
├── examples/              # Code examples and tutorials
├── user_guide/           # End-user documentation
├── conf.py               # Sphinx configuration
├── index.rst             # Main documentation index
├── requirements.txt      # Python dependencies
└── venv/                 # Virtual environment (git-ignored)

Available Build Commands#

Standard Build#

sphinx_build_docs.bat

Builds the documentation for the current branch.

Multi-Version Build#

sphinx_build_multiversion.bat

Builds documentation for multiple Git branches/tags (useful for releases).

API Documentation Generation#

sphinx_autodoc.bat

Regenerates API documentation from Python docstrings in the uvflow/ directory.

Clean Build#

sphinx_clean.bat

Cleans the build directory and sets up Git worktree for deployment.

Writing Documentation#

File Formats#

The documentation supports multiple formats:

Markdown (.md)#

# Page Title

This is a markdown page with **bold** and *italic* text.

## Code Examples

```python
from uvflow.addon_utils import Register

@Register.OPS.GENERIC
class MyOperator:
    def action(self, context):
        print("Hello, UVFlow!")

reStructuredText (.rst)#

Page Title
==========

This is a reStructuredText page.

.. code-block:: python

   from uvflow.addon_utils import Register
   
   @Register.OPS.GENERIC
   class MyOperator:
       def action(self, context):
           print("Hello, UVFlow!")

Documentation Guidelines#

1. File Organization#

  • Place user-facing docs in user_guide/

  • Place developer docs in developer_guide/

  • Place code examples in examples/

  • Use descriptive filenames and folder structure

2. Writing Style#

  • Use clear, concise language

  • Include code examples for technical concepts

  • Add cross-references to related sections

  • Use proper headings hierarchy (#, ##, ###)

3. Code Examples#

  • Always test code examples before including them

  • Use syntax highlighting with proper language tags

  • Include complete, runnable examples when possible

  • Add comments to explain complex concepts

4. Cross-References (example)#

See the [Operator Documentation](../addon_utils/new_operator.md) for details.

Reference the {doc}`../addon_utils/new_property` page.

Adding New Pages#

  1. Create the file in the appropriate directory

  2. Add to table of contents in the parent index.rst or index.md

  3. Build and test locally before committing

Example index.rst entry:

.. toctree::
   :maxdepth: 2
   
   new_page
   existing_page

API Documentation#

Automatic Generation#

API documentation is automatically generated from Python docstrings using Sphinx autodoc:

sphinx_autodoc.bat

This scans the uvflow/ directory and creates .rst files in docs/api/.

Writing Good Docstrings#

class MyClass:
    """Brief description of the class.
    
    Longer description with more details about the class purpose,
    usage patterns, and important notes.
    
    Attributes:
        attribute_name (type): Description of the attribute.
        
    Example:
        Basic usage example::
        
            obj = MyClass()
            obj.method_name()
    """
    
    def method_name(self, param1: str, param2: int = 0) -> bool:
        """Brief description of the method.
        
        Detailed description of what the method does, its behavior,
        and any important considerations.
        
        Args:
            param1 (str): Description of the first parameter.
            param2 (int, optional): Description of the second parameter.
                Defaults to 0.
                
        Returns:
            bool: Description of the return value.
            
        Raises:
            ValueError: When param1 is empty.
            TypeError: When param2 is not an integer.
            
        Example:
            >>> obj = MyClass()
            >>> result = obj.method_name("test", 5)
            >>> print(result)
            True
        """
        if not param1:
            raise ValueError("param1 cannot be empty")
        return True

Automatic Deployment#

GitHub Actions Workflow#

Documentation is automatically built and deployed when changes are pushed to the main branch:

  1. Trigger: Push to main branch

  2. Build: GitHub Actions runs Sphinx build

  3. Deploy: Built documentation is deployed to gh-pages branch

  4. Live: Documentation is available at cgcookie.github.io/uvflow

Workflow Details#

The deployment workflow (.github/workflows/build-deploy-docs.yml):

  1. Checkout code from the repository

  2. Set up Python 3.10 environment

  3. Install dependencies from docs/requirements.txt

  4. Generate API docs with sphinx-apidoc

  5. Build documentation with sphinx-build

  6. Deploy to GitHub Pages using peaceiris/actions-gh-pages

Manual Deployment#

If you need to manually deploy (maintainers only):

# Build documentation
sphinx_build_docs.bat

# Set up gh-pages worktree (first time only)
cd docs/_build
git worktree add -f html gh-pages

# Deploy
cd html
git add .
git commit -m "Update documentation"
git push origin gh-pages

Contributing to Documentation#

Getting Started#

  1. Fork the repository on GitHub

  2. Clone your fork locally

  3. Create a feature branch for your changes

  4. Set up the documentation environment (see Quick Start)

  5. Make your changes and test locally

  6. Submit a pull request

Contribution Workflow#

# 1. Create feature branch
git checkout -b docs/improve-operator-guide

# 2. Make changes
# Edit documentation files...

# 3. Build and test locally
sphinx_build_docs.bat

# 4. Preview changes
# Open docs/_build/html/index.html in browser

# 5. Commit changes
git add .
git commit -m "Improve operator documentation with more examples"

# 6. Push to your fork
git push origin docs/improve-operator-guide

# 7. Create pull request on GitHub

Review Process#

  1. Automated checks run on pull requests

  2. Documentation builds are tested

  3. Maintainer review for content and style

  4. Merge after approval

  5. Automatic deployment to live site

What to Contribute#

High-Priority Areas#

  • User guides for common workflows

  • Code examples for addon_utils features

  • Troubleshooting guides for common issues

  • API documentation improvements

  • Getting started tutorials

Content Ideas#

  • Step-by-step tutorials for UV unwrapping or UV straightening workflows

  • Advanced operator development examples

  • UI guides

  • Performance optimization tips

  • Integration with other Blender addons

Style Guidelines#

Writing Style#

  • Write for your audience (users vs developers)

  • Be concise but complete

  • Use consistent terminology

  • Include practical examples when possible

Formatting#

  • Use proper Markdown/RST syntax

  • Include syntax highlighting for code

  • Use descriptive link text

  • Add alt text for images

  • Structure content with clear headings

Code Examples#

  • Test all code examples

  • Use realistic, practical examples

  • Include necessary imports

  • Add explanatory comments

  • Show expected output when relevant

Troubleshooting#

Common Issues#

Build Errors#

“sphinx-build command not found”

# Ensure virtual environment is activated
call docs\venv\Scripts\activate  # Windows
source docs/venv/bin/activate    # Linux/Mac

# Reinstall dependencies
pip install -r docs/requirements.txt

“Module not found” errors

# Regenerate API documentation
sphinx_autodoc.bat

# Clean and rebuild
sphinx_clean.bat
sphinx_build_docs.bat

Preview Issues#

“Changes not showing”

  • Clear browser cache

  • Rebuild documentation completely

  • Check file paths and links

“Images not loading”

  • Ensure images are in _static/ directory

  • Use relative paths from the documentation root

  • Check image file extensions and case sensitivity

Getting Help#

  1. Check existing documentation for similar issues

  2. Search GitHub issues for known problems

  3. Ask in discussions for general questions

  4. Create an issue for bugs or feature requests

Advanced Topics#

Custom Themes and Styling#

The documentation uses the sphinx-book-theme. To customize:

  1. Edit docs/conf.py for theme options

  2. Add custom CSS to docs/_static/custom.css

  3. Override templates in docs/_templates/

Multi-Version Documentation#

For maintaining documentation across multiple versions:

# Build all versions
sphinx_build_multiversion.bat

# This creates separate documentation for each Git tag/branch

Extensions and Plugins#

Current Sphinx extensions in use:

  • myst_parser - Markdown support

  • sphinx.ext.autodoc - API documentation

  • sphinx.ext.viewcode - Source code links

  • sphinx_multiversion - Multi-version support

To add new extensions, edit docs/conf.py.

Performance Optimization#

For faster builds:

  • Use incremental builds (default)

  • Exclude unnecessary files in conf.py

  • Optimize images before adding them

  • Use caching for external resources

Resources#

Documentation Tools#

Writing Guides#

Blender Development#

Happy documenting! 📚✨

If you have questions or need help, don’t hesitate to reach out through GitHub issues or discussions.

Contents