Some third party Docs are external links, some are rendered inside

[kellertuer]

I noticed, that some documentation of third arty tools like

https://docs.sciml.ai/ManifoldDiffEq/stable/ (thanks for seeing these already btw)
or
https://docs.sciml.ai/FFTW/stable/

are rendered (again) in this repo while they have their own docs ( https://juliamanifolds.github.io/ManifoldDiffEq.jl/stable/ or https://juliamath.github.io/FFTW.jl/stable/) while other menu entries for third party tools like Flux link to external docs.

Is there a rule when docs are “re-rendered” here and when they are linked? I feel linking should be the default if the standalone docs outside SciML exist?

[ChrisRackauckas]

I'm not sure why Flux's ends up linking back.

[kellertuer]

I think it would be nice for Documentations outside the SciML org to be links and not rendered MultiDocs-docs?

[ChrisRackauckas]

But then the taskbar on the top would be gone. An embedding is probably best.

[kellertuer]

But embedding means there is always 2 documentation links/URLs at least if not 2 different versions always, since they are rendered here and in their original place, I think?

[ChrisRackauckas]

No, if it's in iframe it's just the same exact webpage, just embedded.

[kellertuer]

Ah, ok, so outdated docs, which were my first worries, is not a problem. Then my only critique here is, that for external ones being “I-framed-into” the SciML-org, they might be confused to be not-so-third-party but actually SciML projects. This might be misleading for users? Th url is now

https://docs.sciml.ai/ManifoldDiffEq/stable/

from within the docs here but ManifoldDiffEq belongs to JuliaManifolds.

[devmotion]

No, if it's in iframe it's just the same exact webpage, just embedded.

I don't think that's correct, is it? I was just looking into MultiDocumenter for some personal packages and to me it seems it actually copies everything - no iframes, no links, just copies of the existing Documenter output with some tiny fixes and by default previews removed.

As an example, the MCMCDiagnosticTools docs (https://turinglang.org/MCMCDiagnosticTools.jl/stable/) are included in the ArviZ docs: https://julia.arviz.org/MCMCDiagnosticTools/stable/ But if you inspect the ArviZ docs, there are no iframes or embeddings, it's just a plain HTML page. And indeed, if you check the corresponding gh-pages branch (https://github.com/arviz-devs/ArviZJuliaDocs/tree/gh-pages/MCMCDiagnosticTools) you see that it contains a copy of the MCMCDiagnosticTools docs.

So to me it seems that indeed whenever you use Multidocumenter you copy all existing docs and republish them. I guess that's fine (but possibly messes with SEO?) when you "own" the re-published docs but seems a bit strange if it is a third-party project.

[kellertuer]

It messes a bit with SEO, but the JuliaHub copy does that as well.

My main concern is really that this is a surely related but still non-SciML project and the docs currently indicate this differently, when browsing to https://docs.sciml.ai/ManifoldDiffEq/stable/; sure the menu states “Third party solvers”, but the page itself does not. Besides that I am not sure why a copy is necessary. Would a link not be enough?

I am also not so happy about the JuliaHub docs copy, because that leads to google linking to old version therein, at least when I tried a few searches. But sure neither of them is breaking any laws/copyrights. It is just that I am not a fan of either copies and do not see the reason why that should be necessary.

[mortenpi]

No, it's not an iframe, it is a copy. But we could try to experiment with an iframe (and maybe have a small UI indicator saying that "hey, we're just mirroring someone else's docs here).

[kellertuer]

At least an option would be great!

I think for example all SciML-internal packages that are “at home” in this MultiDoc do not necessarily need that indicator but external ones would? My personal preference would still be to not copy external ones, but that might just be my personal preference.

[mortenpi]

I think for example all SciML-internal packages that are “at home” in this MultiDoc do not necessarily need that indicator but external ones would?

Yeah, I assume that https://docs.sciml.ai/ is the canonical home for most of the packages. It's just things like Flux and Ferrite that would get an iframe and an indicator. I have something in mind, so let me try to mock something up.

[mortenpi]

Here's a rough mockup of what I had in mind (the colors might only work in dark mode): https://mortenpi.eu/mockups/sciml-ferrite/

A couple of potential issues that popped into my head though:

• If it's an iframe, those docs will not be included in the site-wide search. You can still use the search within the iframe though.
• The URL won't update as you browse the external package docs (e.g. it will always be https://docs.sciml.ai/Ferrite/stable/).
• If the remote docs change their URL, then the iframe in the SciML docs immediately 404s. But this would just need a new aggregation build with a fix, so probably not a big issue.

So another thing we could do is just inject the small "mirrored documentation" notice, but otherwise keep copying the docs.

[kellertuer]

I like this!

Just locally on my phone I noticed the one line remark at the top could be 2 lines on mobile (if with is quite small) otherwise for example the URL vanishes behind the content that follows below.