Move README content to docstrings & update docs website

[gdalle]

README content is not discoverable by users in the REPL. This PR fixes that by moving the function descriptions to docstrings, and updating the documentation website to reflect that.

• [x] move most README content to docstrings in the main source file
• [x] add links to backend docstrings
• [x] update Documenter to v1.0
• [x] ignore docs/Manifest.toml and activate CompatHelper on docs/Project.toml
• [x] activate PR docs preview: see https://juliadiff.org/AbstractDifferentiation.jl/previews/PR106
• [x] clean up resulting HTML once PR is closed
• [x] clarify dependencies between functions
• [x] explain what @primitive does and how to use it

No actual Julia code has been changed except in docs/make.jl

[gdalle]

I think this might require more discussion and changes in the code, so I'd suggest leaving it for a separate PR.

I agree, but still I think leaving the page in the docs makes sense, if only to show readers that there are two aspects to the package and only one is documented yet.

[codecov[bot]]

Codecov Report

Patch and project coverage have no change.

Comparison is base (df50a8d) 82.94% compared to head (c2014ac) 82.94%.

Additional details and impacted files

```diff @@ Coverage Diff @@ ## master #106 +/- ## ======================================= Coverage 82.94% 82.94% ======================================= Files 8 8 Lines 428 428 ======================================= Hits 355 355 Misses 73 73 ``` | [Files Changed](https://app.codecov.io/gh/JuliaDiff/AbstractDifferentiation.jl/pull/106?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=JuliaDiff) | Coverage Δ | | |---|---|---| | [src/AbstractDifferentiation.jl](https://app.codecov.io/gh/JuliaDiff/AbstractDifferentiation.jl/pull/106?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=JuliaDiff#diff-c3JjL0Fic3RyYWN0RGlmZmVyZW50aWF0aW9uLmps) | `78.40% <ø> (ø)` | | | [src/backends.jl](https://app.codecov.io/gh/JuliaDiff/AbstractDifferentiation.jl/pull/106?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=JuliaDiff#diff-c3JjL2JhY2tlbmRzLmps) | `83.33% <ø> (ø)` | |

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[gdalle]

thanks for the huge merge conflict from JuliaFormatter 🤣

[devmotion]

Ooops, sorry 😬

[gdalle]

I encountered a weird behavior where the cross-references in the docs wouldn't work with the AD shortcut for AbstractDifferentiation, even though I imported it as such in docs/make.jl. This explains the workflow failure on the penultimate commit. Do you think it's a Documenter bug or just me asking too much?

[gdalle]

Generally, I think it's not too bad (maybe even clearer?) if the docs do only use the user-defined convenience alias in the examples.

I do agree, but I don't think it should block this PR.

So maybe one option would be to set the current module to Main.

I looked around and I didn't find a way to do that in the kwargs of Documenter.makedocs, are you aware of one? I would proceed with caution though, cause it might trigger other unexpected behaviors. Maybe it is actually easier to define const AD = AbstractDifferentiation within the module itself, without exporting it?

[devmotion]

Maybe it is actually easier to define const AD = AbstractDifferentiation within the module itself, without exporting it?

This was done initially but caused some problems (would have to look it up though). Generally, my gut feeling is that it is cleaner and easier to let users decide whether and what abbreviation they want to use. import ... as ... was designed for that use case and seems sufficiently concise IMO.

[gdalle]

Thanks for the thorough review!