Migrate gh documentation pages docs to Jekyll

[pq]

It's not clear when this will auto-migrate but when it does it will break our docs on https://dart-lang.github.io/linter/.

[pq]

We might also consider an alternative to GH Pages, such as https://readthedocs.org/.

Thoughts from folks w/ relevant experience welcome!

[zoechi]

@chalin ?

[chalin]

Thanks for the ping @zoechi!

Why not host the docs on https://www.dartlang.org? /cc @kwalrath @kevmoo

Just curious, are the individual pages created by hand or auto-generated? If created by hand, they would be must easier to read and maintain in markdown format.

[pq]

Thanks for chiming in!

Just curious, are the individual pages created by hand or auto-generated?

They're generated by a script. I run it manually for releases and update the gh-pages branch.

[kwalrath]

At one point, we migrated a lot of tools docs off of www.dartlang.org, since in-repo docs were more likely to be kept up to date. If we could keep the source in individual repos yet display them on www.dartlang.org, that would be great.

[chalin]

If we could keep the source in individual repos yet display them on www.dartlang.org, that would be great.

Yes we can do that using submodules (which is what we are doing for the Angular engineering notes of site-webdev).

[chalin]

@kwalrath - shall we pursue this option? @pq - I see that this is marked as High priority. Is there a time limit, and if so, what is it?

[pq]

@chalin : I honestly don't know. That sort of scary threat still shows up in settings but is not specific about when it will happen.

@kwalrath : can you point me to any examples of tools that have their docs displayed on dartlang?

One thing to keep in mind is that the linter is on a very different release cadence from the SDK. This has a few consequences:

1. docs are getting (re)generated roughly weekly if not more frequently
2. there's an unsolved issue of seeing what linter docs correspond to the specific linter shipped with an SDK

The second issue has been around forever and hasn't bothered anyone that I'm aware of but it's worth mentioning if linter docs are going to get more promoted.

[kwalrath]

The angular notes are under https://webdev.dartlang.org/angular/note. (They're extracted from https://github.com/dart-lang/angular/tree/master/doc, which we should probably say on that page, along with version info...)

[chalin]

there's an unsolved issue of seeing what linter docs correspond to the specific linter shipped with an SDK

Well, this could be resolved by hosting the docs on pub. Let me explain: pub now hosts API docs. Each individual lint's "doc" page is rather simple, so the lint's documentation could be written as API docs over the lint rule's class.

[pq]

Thanks @kwalrath!

Regarding versioning another wrinkle is that we generally work from master and only publish docs when we cut a release branch. We might rethink if there's an opportunity to have docs pulled more dynamically. (Anyway, that'd be a good conversation to have.)

As for hosting on pub @chalin, that's another interesting idea. I don't see these quite as API docs but maybe that'd work. Are there any examples of folks hosting anything unusual on pub?

Also note we do have a few pages: an index, a page w/ default options plus pages for each lint (and would likely want the flexibility to add more).

https://github.com/dart-lang/linter/tree/gh-pages

How would that look on pub?

[chalin]

Regarding versioning another wrinkle is that we generally work from master and only publish docs when we cut a release branch.

If you place linter docs under pub/documentation, then that works out.

Are there any examples of folks hosting anything unusual on pub?

I'm not aware of anything unusual, but API docs can make use of any markdown. E.g., see the API docs landing page for the test package: https://pub.dartlang.org/documentation/test/latest

Also note we do have a few pages: an index, a page w/ default options plus pages for each lint (and would likely want the flexibility to add more).

The index page could be part of the linter API doc landing page. For the options, I'm not sure.

I could prototype an addition of these pages to dartlang.org, but it might take a while before I can do that.

[chalin]

Of course, another option is to leave the docs where they are and just embrace the migration to Jekyll :).

[pq]

Thanks for the context @chalin!

Looking at https://www.dartlang.org/tools/pub/pubspec#documentation, I see:

If you specify the documentation: field with a blank value, documentation is created automatically for you, and is linked to from pub.dartlang.com.

I don't see this explained anywhere. Is it documented somewhere?

Of course, another option is to leave the docs where they are and just embrace the migration to Jekyll

😄

This was what I initially thought we'd do but I'm happy to be exploring the options!

[chalin]

pub.dartlang.com

That's a typo, which I'll fix now (.com -> .org).

I don't see this explained anywhere. Is it documented somewhere?

Which part? By "documentation is created automatically", I believe that they are referring to API docs. And I think that the API docs are created even if the documentation field is present: e.g., see the https://pub.dartlang.org/packages/angular page:

cc @kevmoo

[pq]

I believe that they are referring to API docs.

Ah, OK. Not relevant here then. Thanks!

[chalin]

Btw, looking at analytics, I see that folks are looking for lints on dartlang.org :). I'm going to add a redirect rule for now.

[chalin]

Just curious if this is still an issue.

[pq]

Yep. I think it is.

[parlough]

I’m going to close this as the docs now live at https://dart.dev/lints and future work is being tracked on https://github.com/dart-lang/site-www. Thanks all!