[Discussion] Guides/Documentation Improvements

[Hamsterland]

Description

• [ ] Decide on documentation host (Continue with Wyam, Pages, Statiq etc...)
• [ ] Decide on what guides and tutorials to make

Why This is Needed

To make Remora.Discord more approachable to new users who don't neccessarily have the time to slowly learn how it works like most of us have.

Alternatives Considered

N/A

Additional Details

I'd more like to help by writing the guides themselves, I am not really opinionated on which host to use.

[MazeXP]

Possible documentation tools

• DocFX (requires GitHub Action to run on Windows)
• Statiq Docs (had some issues with API docs generation)

[AraHaan]

that is ok to use docfx with github actions on Windows, for pull requests it could also act as an documentation verifier as well which could verify that the docs do not have common errors / issues.

[Nihlus]

This is something that's sorely needed, and I really appreciate it!

As for the tools of choice, I'm fine with whatever as long as it's open-source and cross-platform. No Windows-only stuff, please.

[Hamsterland]

I was a huge advocate for GitBook, but that did not support auto-generation of documention. However, I found this, which is very modern and looks promising!

https://github.com/webmaster442/BookGen

I'll play around with it a little and see how it works out.

[Hamsterland]

Scrap the above idea... That project looks promising but has a long way to go.

[Hamsterland]

@MazeXP @Jax I think DocFX is the sensible choice here. Other options we've explored are either dead/deprecated (Sandcastle, Wyam) or too premature (Bookgen, Statiq).

What do you think of DocFX? The honest truth is that its very mature and has appealing out-of-the-box themes. I particularly like material.

[VelvetToroyashi]

No Windows-only stuff, please.

Isn't DocFX based on .NETFX as well

[VelvetToroyashi]

Though, that Discord theme is pretty appealing...

[Hamsterland]

No Windows-only stuff, please.

Isn't DocFX based on .NETFX as well

It's apparantly cross-platform https://dotnet.github.io/docfx/

[VelvetToroyashi]

Heck. I'd love to write some articles then.

[Hamsterland]

That would be pretty great. You could really just start writing anywhere and we can import it later as DocFX uses markdown.

[VelvetToroyashi]

Aye. I've written articles for D#+.

[Hamsterland]

Sweet. Let's just get @Nihlus final approval before jumping the gun.

[MazeXP]

DocFX 2.0 runs on NetFX. One can run it with Mono on Linux basically

[Nihlus]

I was looking at DocFx in the past and really wanted to use it, but the framework-only builds were a blocker. I was mainly waiting for the 3.0 release which would address this, but perhaps we can start using it anyway. There are released preview versions - worth checking out!

[Nihlus]

Also, we should totally use the Discord theme.

[MazeXP]

DocFX 3,0 does not have the API reference generation inbuilt. That's the most recent branch of 3.0 that has some external reference generation: https://github.com/dotnet/docfx/tree/v3-template

[Nihlus]

So assuming we use DocFx (which I really would like), the next step really needs to be a project plan - what goals do we have for the documentation, what do we want to document, in what format, etc etc - would you be willing to take the lead on that, @Hamsterland?

[MazeXP]

For setting up DocFX in GitHub Actions it would be best to have it run on a windows machine. Alternatively we could also set it up for Linux by using Mono with DocFX.

But as GitHub Actions does also provide Windows machines I do not see a problem about just using Windows for the GitHub Action. As I think the docs should actually be built by CI tasks.

As an alternative to GitHub Action it would also be possible to use AppVeyor for the docs generation. (Free for public projects, 1 concurrent job, no limited usage time per month)

I did already some experiments with DocFX and Remora.Discord:

• GitHub Action: https://github.com/MazeXP/Remora.Discord/blob/docs-improvement/.github/workflows/docs.yml
• DocFX files: https://github.com/MazeXP/Remora.Discord/tree/docs-improvement/docs
• Result: https://mazexp.github.io/Remora.Discord/index.html

[Nihlus]

I would prefer the use of a Linux machine; that way, it's more or less guaranteed to work on other OS's as well.

[MazeXP]

Well, is it useful to be able to build docs locally? For preview locally, as the articles would be written in markdown and most editors support previewing markdown.

[Nihlus]

I think so; testing a failing action is way faster if you can do it locally, as is experimenting with new features.

[MazeXP]

Would Mono be an option for you locally as DocFX 2 is written in NetFX? DocFX 3 is sadly not making any progress regarding API Reference generation.

The only alternative would be Statiq.Docs when following issue gets fixed: https://github.com/statiqdev/Statiq.Framework/issues/244

[Nihlus]

Yeah, I'm fine using Mono; that said, if DocFX 3 doesn't seem like an option in the future, perhaps we should look elsewhere.

[MazeXP]

By new feature you mean a new article in the docs context, i guess?

[Nihlus]

Either a new article or the use of a new or different feature in DocFX itself, such as different themes or page generations.

[MazeXP]

Just came across https://docusaurus.io/. It looks good and easy to setup. Maybe we could use it for Remora. It does not support API reference generation at all for .NET. But to my extent I think it is not required for the beginning of a documentation.

[Nihlus]

I think I tried Docusaurus in the past with pretty good results. The lack of .NET API reference generation is a shame, though - we could, of course, always roll our own from the generated XML files and spit out a format Docusaurus recognizes.

[MazeXP]

How do you think about a separate branch that is then added via git worktree for documentation building.