Development

This section documents contribution workflows, documentation rules, testing, public API policy, and release practices.

• 1. Contributing
  • 1.1. Development Setup
  • 1.2. The Contribution Workflow
  • 1.3. Commit And Pull Request Conventions
  • 1.4. Reporting Issues
  • 1.5. License And Citation
• 2. Documentation Build
  • 2.1. Source layout
  • 2.2. Install documentation dependencies
  • 2.3. Build the HTML documentation
  • 2.4. Clean builds
  • 2.5. Selected-page builds
  • 2.6. Long source-code examples
  • 2.7. Live rebuilds
  • 2.8. Strict builds
  • 2.9. Docs build environment
  • 2.10. Autosummary and generated API pages
  • 2.11. Docstring warnings
  • 2.12. Intersphinx warnings
  • 2.13. GDAL and optional dependency warnings
  • 2.14. Citation warnings
  • 2.15. Build outputs and cleanup
  • 2.16. Recommended contributor workflow
  • 2.17. Continuous integration
  • 2.18. Changelog workflow
  • 2.19. Pre-release checklist
  • 2.20. Troubleshooting
  • 2.21. In short
• 3. Docstring Style
  • 3.1. Why docstrings matter
  • 3.2. Relationship to the API policy
  • 3.3. General rules
  • 3.4. Recognized section order
  • 3.5. Sections to avoid
  • 3.6. Function docstrings
  • 3.7. Parameter style
  • 3.8. Return style
  • 3.9. Units, shapes, and conventions
  • 3.10. Class docstrings
  • 3.11. Dataclass docstrings
  • 3.12. Agent docstrings
  • 3.13. Coordinator and orchestrator docstrings
  • 3.14. Pipeline docstrings
  • 3.15. Pipeline registry docstrings
  • 3.16. Inversion and model docstrings
  • 3.17. AI model docstrings
  • 3.18. CLI helper docstrings
  • 3.19. Optional dependency docstrings
  • 3.20. Warnings, errors, and deprecations
  • 3.21. Examples style
  • 3.22. Cross-references
  • 3.23. Module docstrings
  • 3.24. Private helper docstrings
  • 3.25. Style details
  • 3.26. Common fixes for current warnings
  • 3.27. Review checklist
  • 3.28. Minimal examples by API type
  • 3.29. In short
• 4. Continuous Integration
  • 4.1. Workflow Map
  • 4.2. Main CI Workflow
  • 4.3. Test Job
  • 4.4. Lint Scope
  • 4.5. Test Scope
  • 4.6. Coverage Upload
  • 4.7. Docs Job
  • 4.8. Package Job
  • 4.9. Publish Workflow
  • 4.10. Local Reproduction
  • 4.11. Failure Triage
  • 4.12. Adding CI Coverage
  • 4.13. Release Checklist
  • 4.14. Design Principles
• 5. Coverage improvement TODO
  • 5.1. Purpose
  • 5.2. Definition of done
  • 5.3. Phase 0 – establish a trustworthy baseline
  • 5.4. Phase 1 – expose existing tests in CI
  • 5.5. Phase 2 – protect the core scientific workflows
    • 5.5.1. pycsamt/emtools/tests
    • 5.5.2. pycsamt/site/tests, pycsamt/seg/tests, and pycsamt/z/tests
    • 5.5.3. pycsamt/forward/tests and pycsamt/ai/tests
  • 5.6. Phase 3 – test agents and end-to-end orchestration
    • 5.6.1. pycsamt/agents/tests
    • 5.6.2. pycsamt/assistant/**/tests and pycsamt/pipeline/tests
  • 5.7. Phase 4 – expand format, model, CLI, and UI coverage
  • 5.8. Phase 5 – cover support packages selectively
  • 5.9. Phase 6 – stabilize the new coverage baseline
  • 5.10. Coverage gates
  • 5.11. Recommended local commands
• 6. API Policy
  • 6.1. API design goals
  • 6.2. Public namespace map
  • 6.3. Public, private, experimental, deprecated
  • 6.4. The import rule
  • 6.5. Top-level pycsamt policy
  • 6.6. The pycsamt.api facade
  • 6.7. Agents API policy
  • 6.8. Pipeline API policy
  • 6.9. Inversion and model API policy
  • 6.10. AI and backend policy
  • 6.11. CLI API policy
  • 6.12. Data and result contracts
  • 6.13. Docstring and documentation requirements
  • 6.14. Deprecation policy
  • 6.15. Optional dependency policy
  • 6.16. Testing requirements
  • 6.17. Contributor checklist
  • 6.18. Decision guide
  • 6.19. In short
• 7. Extending pyCSAMT
  • 7.1. The Object Hierarchy
  • 7.2. Choosing A Base
  • 7.3. A Worked Example
  • 7.4. Unit Conventions
  • 7.5. Rules For New Public Classes