Revamp RBTools API documentation.

 






 

 


  Review Request #14497
  —
  Created July 7, 2025 and updated 

 




















 

  

   Information

  





 
 

  david
 









 
 

  RBTools
 









 
 

  master
 









 
 

  
 









 
 

  
 






 




 

  

   Reviewers

  





 
 

  rbtools
 









 
 

  
 






 








 





  


 
 

  
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.

 








  


 
 

  
Built HTML and checked the output.

 







 









 





  

 


 
 

  



 

  
   


    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

   



  
 




 













 






 
 
 

  

   

    

     
    

    
    
     
  • 
      
     
    • 
     
  • 
      
     
    • 
     
  • 
      
     
    • 
     
  • 
      
     
    • 
     
  • 
      
     
    • 
    

   

   

    
     

      Description
      From
      Last Updated
     

    
    



     

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

      		
      
       maubinmaubin
      
      
       
      
     




     

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

      		
      
       maubinmaubin
      
      
       
      
     




     

      
       
       
I think this meant to say "handles all potential error cases"

      		
      
       maubinmaubin
      
      
       
      
     


    
   

  

 







 






  

 



















 




 




 














 





 

  

   




maubin




   

   







  

 



 

  


   

   

    
 
maubin



    
   


  

  

  



    




  1. 
 
    
  
    
   
    Nice refresh of the docs.
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    2. 

















  2. 
 
    
  
  
    
  
 
    
  
    
   
    
    
     
    
      
       docs/rbtools/api/common-use-cases.rst
       


        (Diff revision 1)


       
      
     
    
        
    
     
     
    

     
     
    

        
   
    
  
    
 
    

   
    
    
    




    
 
    
  
  
  

  
  
   Show all issues
  
 
    

    



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

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    3. 






  3. 
 
    
  
  
    
  
 
    
  
    
   
    
    
     
    
      
       docs/rbtools/api/overview.rst
       


        (Diff revision 1)


       
      
     
    
        
    
     
     
    

     
     
    

        
   
    
  
    
 
    

   
    
    
    




    
 
    
  
  
  

  
  
   Show all issues
  
 
    

    



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

 
    
  


    
 
    
 
      

  


    1. 
 
 
      
 
      
  
 
      
 
      
  
      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.
      
 
      

      2. 


 
    


    

 
    

    4. 






  4. 
 
    
  
  
    
  
 
    
  
    
   
    
    
     
    
      
       docs/rbtools/api/overview.rst
       


        (Diff revision 1)


       
      
     
    
        
    
     
     
    

     
     
    

        
   
    
  
    
 
    

   
    
    
    




    
 
    
  
  
  

  
  
   Show all issues
  
 
    

    



    
    I think this meant to say "handles all potential error cases"
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    5. 




  5. 
 
    
  
    
   
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    6. 




  

 
















 



 

  

   




david




   

   

  

 



 

  


   

   

    
 Review request changed

    
   


  

  

  















  

   

    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.
 





 















  

 
















 





 

  

   




maubin




   

   







  

 



 

  


   

   

    
 
maubin



    
   


  

  

  



    




  1. 
 
    
  
    
   
    Ship It!
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    2. 















  2. 
 
    
  
    
   
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    3.