documentation: update headings and descriptions for api reference

[gluonhiggs]

*Issue #1186

Description of changes:

• Remove TOC heading
• Add module descriptions
• Add module aliases, package aliases.

About the module descriptions, I reference the aws official docs, e.g., ahs.

There are private classes in the modules that I update their descriptions. If I do not add their paths to apidoc_excluded_paths, empty pages would exist like this

Therefore, I have to explicitly list them there. If we tolerate the existence of these empty pages, we can unchange doc/conf.py.

Testing done:

Merge Checklist

General

• I have read the CONTRIBUTING doc
• I used the PR title format described in CONTRIBUTING
• I have updated any necessary documentation, including READMEs and API docs (if appropriate)

Tests

-[x] I have run the existing tests. No breaking changes.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (8597aa6) to head (ff36f3a).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #1220   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          169       169           
  Lines        10835     10835           
  Branches      1382      1382           
=========================================
  Hits         10835     10835           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[speller26]

Thank you for the PR! This is looking really good! One thing: the tree should not be fully expanded from the get-go; we only need to include the top-level headings. As well, don't need the "Braket SDK" heading either; in fact, the API reference home should just be what you see when you click Braket SDK.

[gluonhiggs]

I have pushed some changes based on your feedback. To remove the Braket SDK heading, we have to change _apidoc/modules to _apidoc/braket in index.rst. However, whenever we build html, modules.rst is always generated, and it is not used (a warning is raised). Hence, I add modules.rst to exclude_patterns in conf.py.

[speller26]

Looking great! Just a few comments.

[gluonhiggs]

@speller26 I guess you have to trigger the GitHub actions workflows, right?