Documentation revamp - Githubissues

theabhirath commented 2 years ago

The current documentation format is a little weird and Publish exposes a lot of private functions in the API reference as well. There are several steps that need to be decided on:

[x] Migration to Documenter.jl or Pollen.jl. Publish CI times have also been bad, so this should be an easy move. The question is which of Documenter or Pollen would be better suited.
[x] Polishing up the documentation for the Layers module, and exposing the API reference for it in a separate, visible place. This includes custom Layers options like AdaptiveMeanMaxPool being added in #174, which we could even export from Metalhead itself for ease of use
[ ] ~Use the GitHub Wiki feature to~ Create a comprehensive developer documentation inside of the main documentation. This will include stuff like the absolute lowest level API of models (such as the ResNet one from #174), as well as other helpful instructions like the code style (SciML), which will allow new contributors to understand the codebase better before they dive in.

cc @darsnack @ToucheSir @lorenzoh for the Documenter/Pollen migration, which is probably the highest priority on this list

darsnack commented 2 years ago

I would prefer Pollen.jl because it accepts more formats including notebooks.

For the last point, I would prefer to have a developer section directly in the docs (where contributing already lives) instead of enabling the wiki feature. My previous experience with GitHub wikis has been poor, and it does not make sense to split the documentation in two places.

theabhirath commented 2 years ago

One of the main questions I have regarding Pollen is if there is support for documenting multiple versions of the same package? This is something I suspect we will need quite a bit when 0.8 lands, since that will be massively breaking.

lorenzoh commented 2 years ago

Support in Pollen.jl for documenting multiple versions kinda works but is not great rn, i.e. no GitHub Action when a new version is tagged, no version picker in the frontend. Improving this is something I have been working on, but I will have little bandwidth to continue that work until the beginning of September. In parallel, I have been working on making it fully compatible with Documenter.jl syntax. So, I wouldn't propose moving to Pollen.jl right now, but we could either postpone a move or move to Documenter.jl with the option of easily switching to Pollen.jl later once that is possible.

CarloLucibello commented 1 year ago

This issue us is part of the v0.8 milestone. What needs to be done to close it?

FluxML / Metalhead.jl

Documentation revamp #187