Fixes documentation generation for FAKE 5 only modules

[kblohm]

This should fix the documentation generation for FAKE 5 modules that are not referenced in FakeLib.csproj.

I am not sure how to handle modules that have a different API for net46 and netstandard (if that ever happens)

[matthid]

Thanks! Does this duplicate some docs or how does it actually look? (I can check myself but maybe you have already seen it)

[kblohm]

Good point, i forgot to check that :/. It does duplicate some stuff. Looks like every Fake 5 module that is also in FakeLib.

[kblohm]

I could manually add only modules that are not in FakeLib. Another option would be a second index page for old docs and one for new docs?

[matthid]

Second index is probably the way to go, this way we can disable the old one eventually or even add a 3rd one for fake 4. But this already makes by brain hurt, because we have to think about the urls. Currently we use /apidocs but we probably would need to have /apidocs/v4 /apidocs/v5 and /apidocs/v5fakelib or something along these lines ... Feel free to suggest something, I'll need to sleep over this.

[matthid]

This would also solve some feedback I received on how to differentiate if an API is only available in v4 or only in v5.

[kblohm]

If you want to only split up the apidocs and not the modules/tutorials etc. i would either use

• apidocs/v4, apidocs/v5, apidocs/v5/legacy or
• apidocs/fake4, apidocs/fake5, apidocs/fake5/legacy

otherwise putting the version on a higher level and giving each version its own menu with tutorials etc. might also work. But thats probably more work and i am not sure if it is worth it.

What would be the difference between v4 and v5/legacy? Just that v4 does not include any of the new modules and legacy includes everything in fakelib?

I did also manage to just use one index page and hide the duplicates in the razor template. But that is not very pretty :p

[kblohm]

Hi,
i split the API docs page into two pages:

• apidocs/v5: includes all the new FAKE5 modules
• apidocs/v5/legacy: includes the docs for FakeLib

i can of course change the routes to something else.
There are still two "problems":

• I am not sure what to do about a v4 only version in case one is needed.
• Some of the docs (e.g Azure WebJobs) include something along the lines of:

This documentation is for FAKE version 5.0 or later. The old documentation can be found here.

That might be kind of confusing given someone clicked on the docs for FAKE4.

[matthid]

I am not sure what to do about a v4 only version in case one is needed.

I can take care of this. Basically I'd download an old version via nuget ;)

That might be kind of confusing given someone clicked on the docs for FAKE4.

Do you have an suggestion? Technically the text is correct as in FAKE 4 docs that API is not available.

The only thing I'm a bit afraid of is breaking all the current links ...

[kblohm]

I thought about it some more and i would probably do it like this:

• Rename Legacy to Migration, legacy has kind of a bad connotation for a new API. And the API is there to ease migration. Thats not too important though
• Deprecate every one of the old APIs even those that are not yet ported. Right now its kind of hard to see when u can port to version 5. By just replacing every obsolete method from your old buildscript u might still not be able to port but u have no way to tell other then looking up the available API by hand.
• Either remove "This documentation is for FAKE version 5.0 or later. The old documentation can be found here." or replace it with something along the lines of "Additional, old documentation from FAKE version 4 can be found here. It might not be accurate anymore and needs to be ported. Feel free to help by making a pull request"

The only thing I'm a bit afraid of is breaking all the current links ...

I clicked around and i did not find any broken links. But i might have missed some ;). I could just leave the URL for the current version as is and just add a /legacy for the second version. That way its less likely to break something. But its also a little inconsistent.

[matthid]

Rename Legacy to Migration, legacy has kind of a bad connotation for a new API. And the API is there to ease migration. Thats not too important though

I don't have a strong opinion on that.

Deprecate every one of the old APIs even those that are not yet ported.

Yes indeed!

"Additional, old documentation from FAKE version 4 can be found here. It might not be accurate anymore and needs to be ported. Feel free to help by making a pull request"

Technically it has been ported, correct because the new docs are the page you currently look at?

I clicked around and i did not find any broken links.

Yes what I meant is that people have "https://fake.build/apidocs/fake-core-targetoperators.html" added to their favorites or linked on their blog-posts (or whatever) and they will break.

But its also a little inconsistent.

Yes I agree ;). Maybe we should have the new documentation twice, once for compatibility and once on /v5?

Sorry for the ping-pong in this issue :). Huge thanks for looking into this.

[kblohm]

Technically it has been ported, correct because the new docs are the page you currently look at?

For the API docs, yes they are the current ones. But some of the docs e.g https://fake.build/apidocs/fake-azure-cloudservices.html still point to old docs that re not "API" docs but "module" docs? not sure how to call these. E.g. https://fake.build/legacy-azurecloudservices.html. They look more like real documentation and not just API.

Yes I agree ;). Maybe we should have the new documentation twice, once for compatibility and once on /v5?

Some of the links will always break because API moved from old to new. So i would either make a breaking change or just keep the current version under apidocs and then move old stuff to apidocs/v4 and v5 as soon as v6 is out and so on. Or just add a redirect from apidocs to apidocs/v5. But i am also not sure how to handle that.

[kblohm]

I marked all the old stuff as obsolete. I did not check if there are replacements because i assumed all of those are already marked obsolete.
If u dont like the current message, search and replace should make it easy to change it to something else.

[kblohm]

Hi,
do u know if FSFormatting can generate docs that show that a type is obsolete? Right now u cant tell this by just looking at the docs.
I wanted to add a comment over each type and module, but maybe u know how FSFormatting can automate this.

[matthid]

@kblohm Yes basically you define the generation in your razor template: https://github.com/fsharp/FAKE/blob/master/help/templates/reference/module.cshtml Currently the information we get is limited to https://github.com/fsprojects/FSharp.Formatting/blob/master/src/FSharp.MetadataFormat/Main.fs#L27-L149 but I guess in our scenario we would extend them to include attributes (and in particular a property to check for the obsolete attribute, such that this common code doesn't need to be part of the templates)

It shouldn't be too hard to add actually.

[matthid]

Thanks a lot for this! Will try to take a look and hopefully get it out soon.

[kblohm]

The link to the API docs for the legacy version is still called FAKE4.
And i did not copy the FAKE5 version to apidocs (without v5).

[matthid]

Yes I'm looking into those points. Currently I think I'll just generate "redirect" pages into "apidocs" redirecting to "apidocs/v5".
Regarding fake 4 docs I'll tell paket to download fake 4 from nuget and generate docs from it and call the /v5/legacy docs "Fake 5 Migration Reference".

That "Obsolete" is missing is a bit unfortunate indeed.

[matthid]

Ok this is released now on https://fake.build - looks good!