Reorganise the documentation

[mzgubic]

The ChainRules docs are one of my favourite docs. We have been diligently adding clear and concise documentation for every change or feature and the docs serve as a great reference point for experienced users.

However, due to their organic growth, they can be quite confusing for a first time reader trying to get acquainted with the package and find out how to use it. I suppose the 1.0 milestone is a good time to revisit the organisation of the documentation and try to make it more friendly for first time users.

This issue outlines a proposal for the reorganisation of the docs. Let's discuss first and then make the changes. The main proposal is to make Introduction simpler, separate out the maths, and split the rest into pages for rule authors, and AD authors.

Titles in italic are the existing pages to be moved.

---

Introduction

• What is AD, and how does ChainRules fit in
• ChainRules ecosystem organisation
• ChainRules 101: a simple frule and rrule example
• Terminology (Could use Tom's PR, or some of the current 'Terminology' boxes)
• Videos

The maths

• The propagators: pushforward and pullback
• Complex Numbers
• Deriving array rules

How to use ChainRules as a rule author

• Differentials (from introduction)
• Frule and rrule complete example (in contrast to the super light weight one in the intro)
• Writing good rules
• Testing your rules (link to CRTU docs or consolidate)
• Superpowers
  • ProjectTo (from writing good rules)
  • Rule configurations and calling back into AD (exclude the declaring support, which belongs to the AD author page)
  • Opting out of rules (exclude the declaring support)
  • Gradient accumulation
• Converting ZygoteRules.@adjoint to rrules
• Tips for making your package work with AD
• Debug mode

How to support ChainRules rules as an AD package author

• Usage in AD
• Declaring support for calling back into ADs (from Rule configurations and calling back into AD)
• Support opting out of rules (from Opting out of rules)

Design

FAQ

API

---

Open questions:

• FAQ: do we want to keep it? Or should we just structure things to where they belong?
• Should we consolidate CRTU docs in these docs?

I suggest we do this in at least two PRs: The first one moving things, and the second one rewriting the introduction and some other parts.

To do:

• [x] reorganise
• [x] polish the introduction page
• [ ] add complete example for rules in rule author section

[sethaxen]

I think we want to introduce complex numbers before array rules; otherwise use of adjoints makes no sense. We could simply add a callout box at the top saying one can proceed without reading that section and then the first time a decision is made in the array rules section to ensure complex support, we add a callout box saying to go back and read that section for an explanation.

[oxinabox]

Yes, make it so.