Documentation improvements (meta)

[abey79]

Quick and dirty issue to list "early user" documentation issues from my experience.

Coverage holes:

• rr.log_cleared missing from Python ref landing page: rr.log_cleared() is missing from the "Common API" section of the documentation #2348
• Annotation context / class description / annotation info entirely missing from the concepts section: Documentation Annotation Contexts #1337
• Although rr.log_annotation_context is linked from the Python Common API page, there is no link/description for rr.ClassDescription and rr. AnnotationInfo.
• Add an "API Usage Examples" page #2382
• Optimize/multi-stack (square) screenshots of the doc: Update all documentation screenshots to optimised multi-resolution stacks #2457
• Redo rounded-corner screenshots of the doc: Redo documentation screenshots with rounded corners using the built-in screenshot tool #2458
• Space View: Document each type of Space View #3039
• Likewise, Component doc should be improved as follows: Improve Component documentation #3042
  • each component should have a dedicated, linkable paragraph providing data-centric information (what they contain, what's their semantic IF such semantic is universal across its use)
  • in archetypes' docs, the primary and secondary components should be indicated with a bulleted list that also includes the component's semantics in the context of that archetype (e.g. radius means different thing in different places)

For 0.8 only??

• Blueprint stuff entirely missing from the concepts section
• Blueprint stuff entirely missing from the Python common API page (although an "Experimental" section already exists)

Long term/subjective/TBD:

• All API mentioned in docs should link into refs
• Wording around annotation/class stuff "sounds" way more generic that it actually is (see Improving on Annotation Context (meta) #2405)
• Use "book" style to introduce concepts
  • each chapter builds on previous chapter, rather than introducing concepts in isolation and seemingly random order
  • each chapter contains more code examples
  • Next/prev buttons, etc. to encourage a more systematic reading (as opposed to the current "trust your instincts, read specific topic when needed" approach.

[emilk]

Let's clean up what's left to do here

[abey79]

I think we can close this as everything is either:

• done
• properly logged as issues scheduled for planning consideration
• obvious/very long-term/likely to be revisited anyway stuff