make docs a submodule and add documentation stage in CI

[johnnychen94]

I'm not very sure whether it works as expected, but here's what I expect:

• enable documentation build on Images.jl side,
• and furthermore, versioning documentation

If this strategy works, we might also need to adjust the structure of https://github.com/JuliaImages/juliaimages.github.io so that the general folder structure looks normal, it's docs/docs/ at present.

[johnnychen94]

Great that it works, so the next step is to add SSH key pair generated by DocumenterTools to secrets of travis of Images.jl and deploy key(with write permission) of juliaimages.github.io (not Images.jl), which I don't have permission to. @timholy @Evizero

After that, we could merge this PR and then manually make a temp tag (not via Registrator) to check if it successfully versions the documentation.

Or we could use Github Actions for documentation build. An example can be found in DemoCards

[timholy]

I am not sure I fully understand the aim here; what's the goal of building the docs with Images.jl?

[johnnychen94]

Here's the motivation:

Any updates(especially new Images.jl release) should trigger a documentation rebuild, and should tag the documentation when necessary. Currently, documentation is always built on the latest, which isn't so good.

Of course, we could manually tag a release in juliaimages.github.io side, but IMO that's not a programmatic way.

[timholy]

Can we do this through CompatHelper now? Whenever a new release gets made in any dependency that requires a bump in bounds, wouldn't there be a notification?

Oh, wait, all the "0" and "1" in the [compat] section of https://github.com/JuliaImages/juliaimages.github.io/blob/source/Project.toml will block that, right? What if we went back to the idea of declaring specific (minor) versions?

[timholy]

👍 to the idea of versioned docs. But what should that be? AFAICT everyone wants Images.jl to just become a meta-package, and once that's done it is unlikely to release new versions on a regular basis.

[johnnychen94]

What if we went back to the idea of declaring specific (minor) versions?

That works. But actually I'm thinking one step further on how to manage all the documentations organically. For example, if we introduce ImageBinarization into Images.jl, should we add a page to juliaimages.github.io explaining how to use ImageBinarization? If yes, what's the relation between Images's documentation and ImageBinarization's documentation(#542 (comment))?

The map in my mind is:

1. trigger a doc rebuild on each release of sub-packages under JuliaImages
2. host docs of sub-packages as submodules of Images's docs, so that every update on sub-packages' docs syncs to Images's docs. (An alternative might be a simple URL link from Images.jl's docs)

And the role of Image's docs IMO is to

• plot the general map of the ecosystem, design philosophy and dev manual
• host demos
• leave other details to sub-packages

everyone wants Images.jl to just become a meta-package, and once that's done it is unlikely to release new versions on a regular basis.

As long as we limit [compat] of Images.jl to patch level, CompatHelper helps to do so. For example, each patch release of sub-packages triggers a patch release of Images.jl, this also triggers a doc rebuild if we take this PR's strategy. Some discussion about this is on #825

"everyone" is actually "every developer", but from a user's view, he/she doesn't want to using ImageCore, ColorVectorSpace, ImageBinarization, TestImages, ..., neither will he/she track the recent updates of related packages. 😄

[johnnychen94]

Whenever a new release gets made in any dependency that requires a bump in bounds, wouldn't there be a notification?

Actually I want things to go as it should without any notification...

[timholy]

if we introduce ImageBinarization into Images.jl, should we add a page to juliaimages.github.io explaining how to use ImageBinarization? If yes, what's the relation between Images's documentation and ImageBinarization's documentation(#542 (comment))?

I'm torn on this, but in general I don't think it's useful for users to go to ImageCore for documentation on functionality defined in ImageCore, to Colors for its docs, etc. Some packages have their own docs but that's a bit legacy right now. Even ImageFeatures & ImageSegmentation, which are not loaded into Images, have pages on JuliaImages.

When a package has documentation that's also hosted locally, it would be ideal if both sets of docs are in sync. Perhaps we should set up a system where the repo's docs get symlinked prior to building the docs at JuliaImages?

As long as we limit [compat] of Images.jl to patch level, CompatHelper helps to do so. For example, each patch release of sub-packages triggers a patch release of Images.jl, this also triggers a doc rebuild if we take this PR's strategy. Some discussion about this is on #825

That's reasonable. But once we hit 1.0 on packages, then wouldn't we declare bounds as ImageCore = "1"? The idea on semver is that you shouldn't have any breaking changes without bumping the major version. New features get added in minor releases, but since those should break any dependent package, why would we need to register a new release of Images?

[timholy]

We could also use GitHub Actions to write custom logic for rebuilding the docs. Perhaps dating the docs, rather than giving them a version number, makes most sense?

[johnnychen94]

Hmmm, not quite so IMO. I'll draft issue later this week on this more carefully. Now I need to catch up with my own work.