Summary

Revamp RBTools API documentation.

Review Request #14497 — Created July 7, 2025 and submitted Dec. 30, 2025, 10:42 a.m.

Information

Owner

david

Repository

RBTools

Branch

master

Bugs

Depends On

Reviewers

Groups

rbtools

People

Description

This change revamps the main portion of the RBTools API docs to make it
much easier to get started. These changes include:

Significantly reworked and expanded the "Overview" page. This
includes:

Start with the tiniest example that can just instantiate the client
and get the root resource.
Authentication options (new).
What resources are (new).
How to access resource data (simplified).
How to iterate over list resources (new).
How to navigate links between resources (simplified).
Request parameters (simplified)
Expanding resources (new)
Limiting data (new)
Error handling (new)

Renamed "Tutorial" to "Common Use Cases", and updated the content with
improved examples and better Python practices.

Removed the old "Resource Specific Functionality" page, since all of
these are now properly documented in the docs for each resource
subclass.

Testing Done

Built HTML and checked the output.

Commits

Summary	ID
Revamp RBTools API documentation. This change revamps the main portion of the RBTools API docs to make it much easier to get started. These changes include: 1. Significantly reworked and expanded the "Overview" page. This includes: - Start with the tiniest example that can just instantiate the client and get the root resource. - Authentication options (new). - What resources are (new). - How to access resource data (simplified). - How to iterate over list resources (new). - How to navigate links between resources (simplified). - Request parameters (simplified) - Expanding resources (new) - Limiting data (new) - Error handling (new) 2. Renamed "Tutorial" to "Common Use Cases", and updated the content with improved examples and better Python practices. 3. Removed the old "Resource Specific Functionality" page, since all of these are now properly documented in the docs for each resource subclass. Testing Done: Built HTML and checked the output.	9160178d1f29b66d34a6144354f16d32bb3b23bf

Summary

Revamp RBTools API documentation.

This change revamps the main portion of the RBTools API docs to make it much easier to get started. These changes include: 1. Significantly reworked and expanded the "Overview" page. This includes: - Start with the tiniest example that can just instantiate the client and get the root resource. - Authentication options (new). - What resources are (new). - How to access resource data (simplified). - How to iterate over list resources (new). - How to navigate links between resources (simplified). - Request parameters (simplified) - Expanding resources (new) - Limiting data (new) - Error handling (new) 2. Renamed "Tutorial" to "Common Use Cases", and updated the content with improved examples and better Python practices. 3. Removed the old "Resource Specific Functionality" page, since all of these are now properly documented in the docs for each resource subclass. Testing Done: Built HTML and checked the output.

9160178d1f29b66d34a6144354f16d32bb3b23bf

Issues

Description	From	Last Updated
Maybe we should say the content argument instead of "second argument" to encourage people to use keyword args.	maubin	July 10, 2025, 3:42 p.m.
It would be nice to point the user to somewhere where they can see the full API_ERROR_CODES dict.	maubin	July 11, 2025, 8:47 a.m.
I think this meant to say "handles all potential error cases"	maubin	July 10, 2025, 3:42 p.m.

flake8 passed.

JSHint passed.

```
Nice refresh of the docs.
```

docs/rbtools/api/common-use-cases.rst (Diff revision 1)

The issue has been resolved. Show all issues

Maybe we should say the content argument instead of "second argument" to encourage people to use keyword args.

docs/rbtools/api/overview.rst (Diff revision 1)

The issue has been dropped. Show all issues

It would be nice to point the user to somewhere where they can see the full API_ERROR_CODES dict.

david July 11, 2025, 8:56 a.m.

Hmm. I think better would be to link to the error docs in RB, except that's currently not great. I have a WIP change on the RB side for API docs that improves this a lot, so I'm going to hold off on this for now until I have that page available to link to.

docs/rbtools/api/overview.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
I think this meant to say "handles all potential error cases"
```

Commits:

	Summary	ID
	Revamp RBTools API documentation. This change revamps the main portion of the RBTools API docs to make it much easier to get started. These changes include: 1. Significantly reworked and expanded the "Overview" page. This includes: - Start with the tiniest example that can just instantiate the client and get the root resource. - Authentication options (new). - What resources are (new). - How to access resource data (simplified). - How to iterate over list resources (new). - How to navigate links between resources (simplified). - Request parameters (simplified) - Expanding resources (new) - Limiting data (new) - Error handling (new) - Renamed "Tutorial" to "Common Use Cases", and updated the content with improved examples and better Python practices. - Removed the old "Resource Specific Functionality" page, since all of these are now properly documented in the docs for each resource subclass. Testing Done: Built HTML and checked the output.	28c5bd55a11632a89126971b51aa36a1482b22e7
	Revamp RBTools API documentation. This change revamps the main portion of the RBTools API docs to make it much easier to get started. These changes include: 1. Significantly reworked and expanded the "Overview" page. This includes: - Start with the tiniest example that can just instantiate the client and get the root resource. - Authentication options (new). - What resources are (new). - How to access resource data (simplified). - How to iterate over list resources (new). - How to navigate links between resources (simplified). - Request parameters (simplified) - Expanding resources (new) - Limiting data (new) - Error handling (new) 2. Renamed "Tutorial" to "Common Use Cases", and updated the content with improved examples and better Python practices. 3. Removed the old "Resource Specific Functionality" page, since all of these are now properly documented in the docs for each resource subclass. Testing Done: Built HTML and checked the output.	9160178d1f29b66d34a6144354f16d32bb3b23bf

Diff:

Revision 2 (+668 -548)

Show changes

	docs/rbtools/api/tutorial.rst
	docs/rbtools/api/index.rst
	docs/rbtools/api/overview.rst
	docs/rbtools/api/resource-specific.rst

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Ship it!

```
Ship It!
```

Status:: Completed
Change Summary:: Pushed to master (7add07e)