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.

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

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

[devmotion]

Great!

I think usually it's easier to not commit the Manifest file.

write implementer guide

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

[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]

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

@@           Coverage Diff           @@
##           master     #106   +/-   ##
=======================================
  Coverage   82.94%   82.94%           
=======================================
  Files           8        8           
  Lines         428      428           
=======================================
  Hits          355      355           
  Misses         73       73           

Files Changed	Coverage Δ
src/AbstractDifferentiation.jl	78.40% <ø> (ø)
src/backends.jl	83.33% <ø> (ø)

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[devmotion]

I have to turn to something else for a while but I had a look at large parts of the PR. Here are some initial comments (that can probably be extrapolated).

[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?

[devmotion]

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?

Based on the CI log, Documenter tries to resolve the references within the AbstractDifferentiation/AD module - but of course AD does not exist there, only AbstractDifferentiation. So maybe one option would be to set the current module to Main.

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. On the other hand, it creates a slight inconsistency...

[devmotion]

Maybe instead just change /Manifest.toml to Manifest.toml?

[gdalle]

we might need other manifests later on, e.g. for fully reproducible benchmarks

[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!