enhancement: Add enhanced_search_issues API for Jira Cloud using new search/jql endpoint

[skumar36-atlassian]

Overview

This PR introduces two new functions for Jira Cloud:

enhanced_search_issues

• Leverages the new search/jql REST endpoint with nextPageToken-based pagination.
• Replaces the deprecated search API endpoints (GET/POST /rest/api/3/search).
• Allows for either limited or complete fetching of results (when maxResults is set to False).
• Atlassian will remove support for the old search API on May 1, 2025.

approximate_issue_count

• Calls the search/approximate-count API to retrieve an approximate count of issues matching a given JQL query.
• Returns either an integer count or the full JSON response based on the json_result flag.
• Available only for Jira Cloud.

Changes

enhanced_search_issues

✅ Implements nextPageToken-based pagination.
✅ Fetches all results if maxResults evaluates to False; otherwise, it fetches up to the specified limit.

approximate_issue_count

✅ Retrieves an approximate count of issues for a given JQL query.
✅ Returns either an integer count or the full JSON response.

💡 Both functions are decorated with @cloud_api to ensure they are only used on Jira Cloud.
🔹 Jira Cloud users will use these new APIs.
🔹 Jira Server/Data Center users remain unaffected and will continue using the existing APIs.

Deprecation Fix: Explicit Sphinx Configuration

• Read the Docs has deprecated automatic detection of Sphinx/MkDocs configuration files, leading to potential build failures. To ensure stable and predictable documentation builds, we have explicitly defined the sphinx.configuration key in .readthedocs.yaml.
• For more details, refer to the official announcement: Read the Docs Deprecation Notice

Testing & Limitations

Manual Testing

✔️ Validated against a Jira Cloud instance.

Unit Tests

⚠️ Unit tests for these cloud-specific endpoints could not be fully implemented due to challenges in configuring the test environment for Jira Cloud.
🔹 Further work is needed to establish a dedicated Jira Cloud test setup.

Migration & Impact

🚨 Breaking Change

• Atlassian has already deprecated the old search API endpoints, with support ending on May 1, 2025.
• Jira Cloud users must migrate to using enhanced_search_issues and approximate_issue_count to ensure continued compatibility.
• Jira Server/Data Center users are not affected and can continue using the existing APIs.

Additional Context

• This update aligns with Atlassian's deprecation roadmap, improving performance and reliability for Jira Cloud users.
• For any questions or further clarification, please refer to the discussion thread on this PR or reach out via our developer community forum.

---

Please review the changes and let me know if any further modifications are required. 🚀

[github-actions]

Label error. Requires exactly 1 of: bug, enhancement, major, minor, patch, skip-changelog. Found:

[wblondel]

Hey @skumar36-atlassian , thank you for your work!!

I'm not a maintainer of this repo but it seems a label is missing on this PR, preventing a check from passing. Could you add one? Options are bug, enhancement, major, minor, patch, skip-changelog.

[devactivity-app]

@wblondel, ⭐3 XP earned, 🏆First Comment Added completed!
Contribute more to raise your XP/Level, complete challenges for extra achievements! [# for personal dashboard]

[skumar36-atlassian]

/label enhancement

[skumar36-atlassian]

Hey @skumar36-atlassian , thank you for your work!!

I'm not a maintainer of this repo but it seems a label is missing on this PR, preventing a check from passing. Could you add one? Options are bug, enhancement, major, minor, patch, skip-changelog.

Yes, I have tried to add /label enhancement as a comment and update the title with enhancement: keyword, also I am not seeing any option to update it to enhancement. @ssbarnea can you help here?

[skumar36-atlassian]

@ssbarnea , @adehad , @studioj I don't have the necessary permissions to add labels to this PR. Could someone please add the "enhancement" label? Let me know if anything else is needed.