Formatted docs with rstfmt

2026-05-24 14:42:01 +01:00 · 2025-05-28 17:23:04 +01:00
parent c2902166dc
commit 38ae2fa1c7
8 changed files with 360 additions and 312 deletions
@@ -1,265 +1,277 @@
-Development
-===========
+#############
+ Development
+#############

-This guide covers setting up a development environment and contributing to ``read_aconity_layers``.
+This guide covers setting up a development environment and contributing
+to ``read_aconity_layers``.

-Development Setup
-----------------
+*******************
+ Development Setup
+*******************

 Prerequisites
-~~~~~~~~~~~~~
+=============

-* Rust 1.70+ with Cargo
-* Python 3.11+ 
-* Poetry
-* Git
+-  Rust 1.70+ with Cargo
+-  Python 3.11+
+-  Poetry
+-  Git

 Environment Setup
-~~~~~~~~~~~~~~~~~
+=================

-1. **Clone and setup the repository:**
+#. **Clone and setup the repository:**

-   .. code-block:: bash
+   .. code:: bash

      git clone https://github.com/Cian-H/read_aconity_layers.git
      cd read_aconity_layers

-2. **Install dependencies:**
+#. **Install dependencies:**

-   .. code-block:: bash
+   .. code:: bash

      poetry install --with dev,docs

-3. **Setup pre-commit hooks:**
+#. **Setup pre-commit hooks:**

-   .. code-block:: bash
+   .. code:: bash

      poetry run pre-commit install

-4. **Build the Rust extension:**
+#. **Build the Rust extension:**

-   .. code-block:: bash
+   .. code:: bash

      poetry run maturin develop

-Code Style and Quality
----------------------
+************************
+ Code Style and Quality
+************************

 This project uses several tools to maintain code quality:

 Python Code
-~~~~~~~~~~~
+===========

-* **Ruff**: For linting and formatting
-* **MyPy**: For type checking  
-* **Pytest**: For testing
+-  **Ruff**: For linting and formatting
+-  **MyPy**: For type checking
+-  **Pytest**: For testing

 Run quality checks:

-.. code-block:: bash
+.. code:: bash

   # Format and lint Python code
   poetry run ruff format .
   poetry run ruff check .
-   
+
   # Type checking
   poetry run mypy .
-   
+
   # Run tests
   poetry run pytest

 Rust Code
-~~~~~~~~~
+=========

-* **rustfmt**: For formatting
-* **clippy**: For linting
-* **cargo test**: For testing
+-  **rustfmt**: For formatting
+-  **clippy**: For linting
+-  **cargo test**: For testing

 Run quality checks:

-.. code-block:: bash
+.. code:: bash

   # Format Rust code
   cargo fmt
-   
-   # Lint Rust code 
+
+   # Lint Rust code
   cargo clippy
-   
+
   # Run Rust tests
   cargo test

-Testing
-------
+*********
+ Testing
+*********

-The project includes comprehensive tests for both Python and Rust components.
+The project includes comprehensive tests for both Python and Rust
+components.

 Running Tests
-~~~~~~~~~~~~~
+=============

-.. code-block:: bash
+.. code:: bash

   # Run all tests
   poetry run pytest
-   
+
   # Run with coverage
   poetry run pytest --cov=read_aconity_layers
-   
+
   # Run Rust tests
   cargo test

 Test Structure
-~~~~~~~~~~~~~~
+==============

-* **Python tests**: Located in ``tests/`` directory
-* **Rust tests**: Integrated into ``src/rust_fn/mod.rs`` 
-* **Property-based tests**: Uses ``arbtest`` for Rust property testing
-* **Regression tests**: Validates against known good outputs
+-  **Python tests**: Located in ``tests/`` directory
+-  **Rust tests**: Integrated into ``src/rust_fn/mod.rs``
+-  **Property-based tests**: Uses ``arbtest`` for Rust property testing
+-  **Regression tests**: Validates against known good outputs

 Adding Tests
-~~~~~~~~~~~~
+============

 When adding new functionality:

-1. **Add Rust tests** in the appropriate module
-2. **Add Python integration tests** in ``tests/``
-3. **Update regression tests** if output format changes
-4. **Add property tests** for mathematical functions
+#. **Add Rust tests** in the appropriate module
+#. **Add Python integration tests** in ``tests/``
+#. **Update regression tests** if output format changes
+#. **Add property tests** for mathematical functions

-Documentation
-------------
+***************
+ Documentation
+***************

 Building Documentation
-~~~~~~~~~~~~~~~~~~~~~~~
+======================

-**Prerequisites**: You need the Rust toolchain installed for ``sphinxcontrib-rust`` to work.
+**Prerequisites**: You need the Rust toolchain installed for
+``sphinxcontrib-rust`` to work.

-.. code-block:: bash
+.. code:: bash

   # Install documentation dependencies
   poetry install --with docs
-   
+
   # Build documentation
   cd docs
   make html
-   
+
   # Or build manually
   poetry run sphinx-build -b html . _build/html
-   
+
   # Serve locally (optional)
   make serve

 Documentation Structure
-~~~~~~~~~~~~~~~~~~~~~~~
+=======================

-* **docs/conf.py**: Sphinx configuration
-* **docs/index.rst**: Main documentation page
-* **docs/python/**: Python API documentation
-* **docs/rust/**: Rust API documentation
-* **docs/*.rst**: User guides and tutorials
+-  **docs/conf.py**: Sphinx configuration
+-  **docs/index.rst**: Main documentation page
+-  **docs/python/**: Python API documentation
+-  **docs/rust/**: Rust API documentation
+-  **docs/\*.rst**: User guides and tutorials

 The documentation automatically generates API references from:

-* Python docstrings and type hints
-* Rust documentation comments (``///`` and ``//!``)
-* Type stub files (``*.pyi``)
+-  Python docstrings and type hints
+-  Rust documentation comments (``///`` and ``//!``)
+-  Type stub files (``*.pyi``)

 **Note**: For Rust API documentation to work properly, you need:

-1. Rust toolchain installed (cargo, rustfmt)
-2. Proper Rust doc comments in your source code
-3. The ``sphinxcontrib-rust`` extension configured correctly
+#. Rust toolchain installed (cargo, rustfmt)
+#. Proper Rust doc comments in your source code
+#. The ``sphinxcontrib-rust`` extension configured correctly

-Contributing
------------
+**************
+ Contributing
+**************

 Workflow
-~~~~~~~~
+========

-1. **Fork the repository** on GitHub
-2. **Create a feature branch** from ``main``
-3. **Make your changes** following the coding standards
-4. **Add tests** for new functionality
-5. **Update documentation** as needed
-6. **Run the full test suite** to ensure everything works
-7. **Submit a pull request**
+#. **Fork the repository** on GitHub
+#. **Create a feature branch** from ``main``
+#. **Make your changes** following the coding standards
+#. **Add tests** for new functionality
+#. **Update documentation** as needed
+#. **Run the full test suite** to ensure everything works
+#. **Submit a pull request**

 Pre-commit Checks
-~~~~~~~~~~~~~~~~~
+=================

 The project uses pre-commit hooks that run automatically:

-* Code formatting (Ruff, rustfmt)
-* Linting (Ruff, Clippy)
-* Type checking (MyPy)
-* Version bump validation
-* Poetry validation
+-  Code formatting (Ruff, rustfmt)
+-  Linting (Ruff, Clippy)
+-  Type checking (MyPy)
+-  Version bump validation
+-  Poetry validation

 These checks must pass before commits are accepted.

 Release Process
-~~~~~~~~~~~~~~~
+===============

-1. **Update version** in ``Cargo.toml`` (triggers version validation)
-2. **Update changelog** if applicable
-3. **Ensure all tests pass**
-4. **Create a release** on GitHub
-5. **CI automatically builds and publishes** wheels to PyPI
+#. **Update version** in ``Cargo.toml`` (triggers version validation)
+#. **Update changelog** if applicable
+#. **Ensure all tests pass**
+#. **Create a release** on GitHub
+#. **CI automatically builds and publishes** wheels to PyPI

-Architecture Notes
------------------
+********************
+ Architecture Notes
+********************

 The library is structured in two main components:

 Rust Core (``src/rust_fn/``)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+============================

-* **High-performance file I/O** using CSV reader
-* **Parallel processing** with Rayon
-* **Memory-efficient array operations** with ndarray
-* **Coordinate correction algorithms**
+-  **High-performance file I/O** using CSV reader
+-  **Parallel processing** with Rayon
+-  **Memory-efficient array operations** with ndarray
+-  **Coordinate correction algorithms**

 Python Bindings (``src/lib.rs``)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+================================

-* **PyO3 integration** for seamless Python interop
-* **Error handling** conversion from Rust to Python exceptions
-* **NumPy integration** for zero-copy array passing
-* **Type annotations** via stub files
+-  **PyO3 integration** for seamless Python interop
+-  **Error handling** conversion from Rust to Python exceptions
+-  **NumPy integration** for zero-copy array passing
+-  **Type annotations** via stub files

 Performance Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+==========================

-* File I/O is the primary bottleneck
-* Parallel processing scales well with core count
-* Memory usage is proportional to dataset size
-* Coordinate corrections use vectorized operations
+-  File I/O is the primary bottleneck
+-  Parallel processing scales well with core count
+-  Memory usage is proportional to dataset size
+-  Coordinate corrections use vectorized operations

-Common Development Tasks
------------------------
+**************************
+ Common Development Tasks
+**************************

 Adding a New Function
-~~~~~~~~~~~~~~~~~~~~~~
+=====================

-1. **Implement in Rust** (``src/rust_fn/mod.rs``)
-2. **Add Python binding** (``src/lib.rs``)
-3. **Update type stubs** (``read_layers.pyi``)
-4. **Add tests** for both Rust and Python
-5. **Update documentation**
+#. **Implement in Rust** (``src/rust_fn/mod.rs``)
+#. **Add Python binding** (``src/lib.rs``)
+#. **Update type stubs** (``read_layers.pyi``)
+#. **Add tests** for both Rust and Python
+#. **Update documentation**

 Debugging Build Issues
-~~~~~~~~~~~~~~~~~~~~~~
+======================

-* **Check Rust version**: Must be 1.70+
-* **Verify PyO3 compatibility**: Should match Python version
-* **Clear build cache**: ``cargo clean`` and ``poetry env remove --all``
-* **Check dependencies**: Ensure all dev dependencies are installed
+-  **Check Rust version**: Must be 1.70+
+-  **Verify PyO3 compatibility**: Should match Python version
+-  **Clear build cache**: ``cargo clean`` and ``poetry env remove
+   --all``
+-  **Check dependencies**: Ensure all dev dependencies are installed

 Profiling Performance
-~~~~~~~~~~~~~~~~~~~~~
+=====================

 For Rust code:

-.. code-block:: bash
+.. code:: bash

   # Profile with perf (Linux)
   cargo build --release
@@ -268,7 +280,7 @@ For Rust code:

 For Python integration:

-.. code-block:: bash
+.. code:: bash

   # Profile with py-spy
   pip install py-spy