[Connector SDK] Documentation, API reference (Sphinx + docstrings), and developer guides #6050
Description
[Connector SDK] Documentation, API reference (Sphinx + docstrings), and developer guides
Context
The Connector SDK currently lacks consistent documentation: docstrings use mixed formats (Google, NumPy, reStructuredText), there is no generated API reference, and no developer guides exist for common tasks like creating an OCTI entity. This makes the SDK harder to use, harder to maintain, and prevents automated doc verification via doctest.
Problem / Objective
| Problem | Impact |
|---|---|
| Inconsistent docstring formats across codebase | Poor readability, doctest.testmod() cannot run |
| No generated API reference | Developers must read source code to understand the SDK |
| No developer guides / tutorials | High onboarding friction for connector authors |
| Documentation not hosted alongside code | Hard to discover and maintain |
Proposed Solution
1. Standardize docstrings
- Adopt Google docstring format across the entire SDK codebase.
- Always include
ReferencesandDatefields in docstrings. - Enable
doctest.testmod()to run seamlessly on code snippets.
2. Generate ReST files with Sphinx
- Configure Sphinx to parse the SDK codebase and produce reStructuredText output.
- This is the foundation for the API reference generation.
3. Generate API reference with Sphinx
- Use Sphinx to generate a full API Reference from docstrings.
- Output as ReST files, hosted on GitHub (e.g.
connectors_sdk/docs/api/).
4. Create "How to create an OCTI entity" guide
- Write a tutorial (Markdown) explaining how to instantiate an OCTI entity using the SDK.
- Must include code block examples.
- Hosted on GitHub (e.g.
connector_sdk/docs/).
Additional Context
- This effort may be split into separate PRs per workstream