Rewrite build process

[jgardella]

This PR rewrites the build process, mostly based on the Waypoint template.

• build.fsx updated to use Waypoint template
• Docs are generated using Fornax.
• Instructions for building and modifying docs added to README
• Changelog updated to follow keepachangelog format.
• Travis and Appveyor replaced with GitHub Actions. There is an action for building which runs to validate PRs, one for publishing updates to the documentation, and one for publishing a release to GitHub and Nuget when a tag is pushed.

[jgardella]

@duckmatt Would appreciate if you could pull this branch and try to go through the build and docs locally. Let me know if you have any issues and what you think of the docs generated by Fornax.

Do you have any idea why some unit tests have started failing with these changes?

[duckmatt]

I've checked it out locally and the tests are passing for me interestingly. However I do have to disable the msbuild linting for FSharpLint.FunctionalTest.fsproj, fails with:

Exec: EXEC(0,0): error : MSBuild could not load the project file C:\Users\p4rk0\github\j-fsharplint\tests\FSharpLint.FunctionalTest\FSharpLint.FunctionalTest.fsproj because: InvalidProjectFileMessage
Exec: C:\Users\p4rk0\github\j-fsharplint\Directory.Build.targets(7,4): error MSB3073: The command "dotnet fsharplint -f msbuild lint --lint-config C:\Users\p4rk0\github\j-fsharplint\/fsharplint.json C:\Users\p4rk0\github\j-fsharplint\tests\FSharpLint.FunctionalTest\FSharpLint.FunctionalTest.fsproj" exited with code -1.

Not anything immediately obvious that is wrong with the project file

[jgardella]

Yeah, I was getting similar issues with linting certain projects, however it was inconsistent; it would sometimes fail for that project, and other times fail for another project. The issues does always seem to be with the test projects though.

Weird about the tests failing for me... let me verify if there's anything I have set up locally that could be causing it.

[duckmatt]

It's good with the docs becoming consistent with some other projects. There's a couple of minor issues, but probably good enough for them to be separate PRs, the things I've spotted:

• On my display the content of the pages is very narrow (reference image below), the Ionide docs appear about double the width
• On the nav bar HOW-TO GUIDES always shows as selected
• On the nav bar the nested nav items always show below the navigation rather than directly below their parent nav item

[jgardella]

A few updates, after doing a git clean the all the tests are passing again. @duckmatt I made some changes to address the your feedback, I may make some more styling changes but if you could take a look again to check if it looks good, specifically the page width.

There is still an issue with the build being flaky when done through FAKE with the new build script... I did some a investigation into this but couldn't really find anything out. The build works consistently when the Directory.Build.targets file is disabled, which stops the linter from running as part of the build. My suspicion is perhaps that the internal calls FSharpLint makes to MSBuild to get info for the projects may be causing some conflicts when they are done alongside an already running MSBuild.

[jgardella]

@duckmatt I am hoping #437 could possible resolve these build issues, if it is a reasonable change.

[Krzysztof-Cieslak]

Hey, let me know if you need any help with Fornax/Waypoint template.

On my display the content of the pages is very narrow (reference image below), the Ionide docs appear about double the width

Yes, I probably have changed margins in Ionide and forgot to port back changes to the template

On the nav bar HOW-TO GUIDES always shows as selected

This will change if you go to the page from another group - basically marked as selected is a group to which current page belongs. It probably should be changed.

On the nav bar the nested nav items always show below the navigation rather than directly below their parent nav item

This is by design - it was inspired by Elixir's Hexdoc documentation (example: https://hexdocs.pm/phoenix/Phoenix.html)

[jgardella]

Thanks @Krzysztof-Cieslak and thanks for the template! It has been a great starting point for doing this update. Things seem to be mostly working aside from the things @duckmatt pointed out.

To me it is a bit confusing that the nav bar highlights the group for the current page, instead of what you have clicked on and have currently active. Tried to make that change but it was not as straightforward as I hoped, so I will leave it as is for now.

Aside from that, this update is pretty much done. I will do some more cleanup for the docs, and I still need to figure out why the MSBuild task to run the linter fails inconsistently when run through the FAKE build, although it works consistently through the IDE.

[jgardella]

I discovered that when the new GitHub action runs on my fork, the build also passes consistently, even though it is using the same build script that is failing locally. I tried re-cloning the branch a couple of times to check this and the build also worked consistently, but again would fail again in any additional runs. It seems like a file must be created on the first build that causes subsequent builds to fail, and is not being cleaned up the Clean step.

[jgardella]

Hey @duckmatt, this is pretty much ready to go, can you add the NUGET_KEY to the repo secrets? With the changes in #442 the lint task seems to work consistently when building locally, I am just waiting for the 0.16.1 version to be available. Also added myself to the maintainers list (pending your 👍 ).

[duckmatt]

Nice, looks good, added a few comments but minor so could be another pull request for those. One small request though, for future PRs could they be a little more broken up? This one may have been a little easier to read if the Fornax change was its own PR

Added the NUGET_KEY to the secrets 👍

[jgardella]

Yes, agreed, I usually try to keep my PRs small and focused; in this case though I kept all these changes together as they are all related to using the Waypoint template (Fornax included). But point taken, the Fornax part of that probably could have been done separately.

[jgardella]

Sorry @duckmatt, I forgot one thing, could you also add the PERSONAL_TOKEN secret; it should be your GitHub personal access token. This is used to automatically build and push the docs to the gh-pages branch. You may also have to update the repo to host the docs from that branch instead of master.