Update Docs and Tutorials

[StFroese]

Issue for collecting required updates/reworks of the documentation and tutorials. Just add stuff if you think something needs an update.
Initially I will just add every chapter of the docs.

Updates

Please check a box if you think this needs an update and also leave a comment on why you think this is required.

Getting Started For Developers

• Get the ctapipe software
• Developing a new feature or code change
• More Development help

Development Guidelines

• Style Guide
• Code Guidelines
• Support Libraries
• Making and Accepting Pull Requests
• Maintainer Info
• For ROOT users

Tutorials

• Getting Started with ctapipe
• Analyzing Events Using ctapipe
• Coordinates usage in ctapipe
• Exploring Raw Data
• Explore Calibrated Data
• Make a theta-square plot

Examples

• Basic Image Cleaning and Dilation
• Use N-dimensional Histogram functionality and Interpolation
• Convert camera images to pixels on a square grid
• Working with Instrumental Descriptions
• Example of a Camera Display
• Using Container classes
• Creating command-line Tools
• Using the ctapipe Provenance service
• Writing Containers to a tabular format

Command-Line Tools

• Data Processing Tools
• Other Tools

Frequently Asked Questions

• Technical Issues

Data Models

• CTAPipe Data Model

New

This lists all new stuff that has so be added to the docs. Link the PRs or issues.

• Update tutorials that require CameraFrame for image processing Drop support for CameraFrame in ImageProcessor #2141
• Machine Learning Tutorial #2135

Additional questions

Some questions that came up while writing this

• What about the Change Log in the docs, do we need this?
• References should be updated if your code comes from a paper (e.g New 3D shower model  #1996 should do this)
• Do we need Tutorials and Examples? Seems kind of redundant to split them

[kosack]

• The main need is to add some new tutorials about running the command-line tools to do a standard analysis. Nearly all the others need some small updates, but they are mostly ok. I can help to clean those up.

• The ChangeLog hasn't been consistently updated - we should switch to using towncrier as mentioned in Setup towncrier for automatic changelog generation #1995

• For the tutorials vs Examples question: the idea were tutorials were higher-level and relate to analysis, while examples were just quick demos of various API features. But if we add a command-line analysis tutorial (or more than one), we should split the Tutorials section into : API Tutorials and Command-line Tutorials, so the hierarchy is:

  • Analysis Tutorials: Command-line and standard analyses (where most users should start)
  • API tutorials (for advanced users)
  • API examples (for developers)

[kosack]

Gammapy's documentation is also a good example of how this all could be re-structured to be simpler. The order is better as well, rather than starting with developers, start with users:

• Getting Started
  • setup
  • core tutorials
• User's guide
• API reference
• Developer's guide

[StFroese]

Also as mentioned in #2135, we should switch to jupytext as suggested by @kosack

[StFroese]

Get the ctapipe software should be updated with #2087

[StFroese]

#2144 towncrier changelog