Plumber: Document plumber decoration syntax / programmatic syntax

[meztez]

I think plumber documentation content is in need of some love. All the pieces are there but it could definitely be improved now that pkgdown has been merged in main.

Todoc:

• [ ] Add "Request documentation" issue template
• [ ] Plumber decoration syntax
  
  
  
  • [ ] Global API tags
  
  
  • [ ] apiTitle
  
  
  • [ ] apiDescription
  
  
  • [ ] apiTOS
  
  
  • [ ] apiContact
  
  
  • [ ] apiLicense
  
  
  • [ ] apiVersion
  
  
  • [ ] apiHost
  
  
  • [ ] apiBasePath
  
  
  • [ ] apiSchemes
  
  
  • [ ] apiConsumes
  
  
  • [ ] apiProduces
  
  
  • [ ] apiTag
  
  
  • [ ] Block tags
  
  
  • [ ] Parameters
    
    
    
    
    
    • [ ] Type
    
    
    
    • [ ] Required
    
    
    
    • [ ] IsArray
    
    
    
  
  
  • [ ] Responses
  
  
  • [ ] Routes
  
  
  • [ ] Serializers / Images
    
    
    
    
    
    • [ ] Serializers options
    
    
    
  
  
  • [ ] Filters
  
  
  • [ ] Router modifier
  
  
  • [ ] Assets
  
  
  • [ ] Preempts
  
  
  • [ ] Comments
  
  
  • [ ] Tags
  
  
• [ ] Programmatic use (how to do the above programmatically) with pr$... methods
  
  
  
  • [ ] How to use $handle ... to programmatically describe API
  
  
• [ ] Concepts
  
  
  
  • [ ] The request object req (already mostly done)
  
  
  • [ ] The response object res (already mostly done)
  
  
  • [ ] Filters
  
  
  • [ ] Preempts
  
  
  • [ ] Serializers
  
  
  • [ ] Parsers
  
  
  • [ ] UIs
  
  
  • [ ] Hook steps
  
  
• [ ] Advanced usage / DIY
  
  
  
  • [ ] Create your own...
  
  

Think about how a user would first interact with the package and build documentation around that.

If someone is game, dust off old photoshop skills and do a cheatsheet.

Let's aim just below shiny god tier level of documentation.

Loving the new logo

[schloerke]

I know @blairj09 has started a cheat sheet.

@meztez (and anyone reading this), do you mind started a list here? Anything and everything that looks like it could be improved or added as it is missing. (A rolling list of checkboxes.) I’d be happy to keep it organized.

I hope to have the pkgdown PR merged this coming Tuesday

Thank you again for your help!

---

@meztez 👏👏👏

[schloerke]

pkgdown branch has been merged. Any "non-release" version of plumber will produce docs in https://www.rplumber.io/dev . Once on a release version, https://www.rplumber.io/ will be updated.

Added in https://github.com/rstudio/plumber/commit/e86ffe8756e70ee6a3a465e5808815f365415123#diff-f993a2f0f4d14c58ff3c137196ec6bf4R3-R4

[blairj09]

Yes - my plan is to work on doc updates and a cheatsheet to coincide with the release.

[meztez]

I believe most of the points here have been covered. Closing this one. Will follow other individual docs issues.