Finally having fixed the majority of the issues caused by moving from a DocFX website to a Docusaurus one, we are back developing RSML. Our current focus has been on the lexer, but we've also been doing several other things...

Launching a Patreon​

While still a work in progress, we have officially launched our Patreon page! That's right: you can now support the development of your favorite OAS tools, so we can keep working on them and providing a powerful, free and open-source ecosystem.

Better analysis​

Recently, we started using Sonar's analysis tooling, because it allows us to flag issues that could have potentially gone unnoticed in our codebases: Sonar ensures our code is safe, tested, maintainable and reliable.

The rebrand nobody saw coming​

OceanApocalypseStudios -> OceanApocalypse.

Yeah, not much to say about this one. We are currently updating lockups, projects and whatnot. Rebranding is a nuisance, but we're rebranding now so we avoid rebranding later on, which would be awful.

This has been done to dissociate the OAS brand with game development, as we are not gaming-centric. If anything, we haven't made any games... for now... No spoilers, but I can promise you something is in the works.

Well, it was quite a short article -- probably my shortest yet. Well, it serves its purpose of containing all you need to know about recent news... without having you read through a 25 minute article.

Thank you for dropping by and reading! ❤️

P.S.: more blog content coming soon

In this article, I'll explain why this change was considered and ultimately decided on. I should probably warn you, though: it's going to be a long article!

The state of DocFX​

As of writing this article, DocFX is hosted under Microsoft's .NET project yet seems to receive little to no attention. Microsoft clearly uses a different - internal only - tool for their massive API browser inside Microsoft Learn. It's the only way to explain why DocFX seems to be so "behind" in all of its features: how could it ever be what Microsoft is actually using if it lacks the basic features you can see in Microsoft Learn's API browser?

In a video part of Microsoft's On .NET series, Hot Reload support for DocFX is mentioned, yet, as this issue makes clear, barely nothing was done regarding it.

Another feature we considered essential yet was not present in DocFX was organizing exports for multiple target frameworks. Of course it allows us to export for multiple frameworks, but as for organizing said exports? No. If you just use DocFX and export to api/net10.0, api/net8.0 and whatnot, you'll find UIDs clash, because DocFX does not take into account the possibility of the same namespace (in different frameworks) being included in the documentation more than one time.

What about DocFX alternatives?​

There aren't any real alternatives to DocFX. There are quite a few open-source CLI tools that output Markdown documentation from .NET assemblies, but I found those either lacked features (such as not recognizing C# 14 extension members, which we use in RSML) or their output was not organized enough.

This led to us moving away from DocFX as the static site generator, and using it only for the exportation ability (docfx metadata), which is also slightly broken in its own way, but it's objectively better than nothing.

Our move to Docusaurus​

We moved to Docusaurus, as it provided a lot of useful features with very simple setup. We could easily set up documentation versioning and even support for languages other than English.

Using it seemed effortless until we reached the multimillion-dollar question: "what about RSML's API reference?"

So what was the issue? Well, DocFX is greedy! Let me explain: DocFX is made for DocFX. When you export an API reference with DocFX, it exports it expecting DocFX itself to use it to generate the site. This means exports are filled with things Docusaurus does not, in any way, understand. Here are two major examples:

• Anchors in headings
• Backslash-escaping

We tried multiple things, but eventually settled for a sanitization script (which is currently private, as it's still being cleaned up) that runs before exporting the API reference with DocFX.

The sidebar issue​

At the time, Docusaurus was auto-generating the sidebar. Well, DocFX actually just exports everything in the same directory with no organization whatsoever: the Docusaurus sidebar was an absolute mess because of this.

We quickly put together some small, somewhat messy, functions that allowed DocFX to generate an actual organized and pretty sidebar. This sadly took quite some time, all thanks to a tool that seems to be barely supported nowadays.

The final result​

Despite the major difficulties setting everything up, we have to say the site looks extremely clean now. Docusaurus does provide a refreshing and modern UI for the static sites it generates.

With the project in development after a short break, and the documentation finally picking up, we believe RSML has a shiny future ahead of it.

Today, we have officially hit the following milestone in RSML: 400 test methods... for a single class... and it's still not fully tested. Before you bring your anti-testing and Console.WriteLine() pitchforks forward, let us explain why we have implemented that many test methods...

Context matters​

In this case, context matters a lot. The class that has received this much testing attention is ReadOnlyStringBuffer, and it serves as the simplest buffer available in the entirety of the official RSML API, yet 400 tests were only half* of what was needed to get it to work properly.

At OceanApocalypse, we believe testing buffers and big language components (such as lexers and parsers) is imperative to ease the task of getting them to work correctly. If this means testing a lot, then it's a sacrifice that we believe is worth making.

It's worth mentioning this does not mean in any way that we believe testing is only relevant when the components are critical: testing is still important when they're not --- the only difference is that it's even more important when the components are critical.

Following the same rationale, we are not saying quantity matters more than quality: RSML could have 9000 tests and could be a broken mess or have 10 tests and work perfectly. We believe a good combination of both is the best compromise a developer can choose.

*This is an assumption, based on the current amount of test methods and the amount of methods that are yet to be tested.

Expecting more tests?​

One word: yes. Not because we love writing tests, but because there are still methods that are publicly exposed yet are fully untested by now. Hopefully, they won't stay that way for much longer, and I'll be happy to write a new article once we can finally mark #60 as closed.

Like I said, this was quite a small article, and a bigger one is to be expected soon.

Thank you for dropping by and reading! ❤️

Today marks the day we, at OceanApocalypse, have officially ditched mkdocs for DocFX. Throughout this article, we'll be focusing on what aspects of Red Sea Modern Language lead to this decision and what it affects.

Why change?​

The main reason for the change was convenience. We're a small team and, because of that, it takes some time to release the projects and it also takes time to write documentation for them, such as guides and walkthroughs, as well as some minor articles for those following RSML's development.

Back when we were using mkdocs, we needed to manually create the API reference: it was not fun. We ended up having the XML documentation in the source code and then we had to essentially port it manually to Markdown --- it felt like a huge waste of time that could have been put into creating walkthroughs or expanding RSML's online presence.

DocFX, unlike mkdocs, is made for .NET primarily, so it automatically creates API references from the source projects, allowing us to focus on the more important tasks, which are the ones that require manual and granular control.

We want to clarify we are not saying mkdocs is not great: it is! However, for our case (a .NET library with XML comments), there was a better alternative, one that reads those very same XML comments and, using the built DLL, generates meaningful documentation from that.

Is the site fully finished?​

Nowhere near finished 🙃

We are still working on v3.0.0-prerelease1, which means the site will also be updated frequently with new documentation, guides and whatnot. Even if we pretend for a second no more documentation will be added (which is unthinkable, as the site still has pages marked with "TODO"), we will change some aspects of the site's design.

We, at OceanApocalypse, are constantly working on both new and existing projects and are now focused on crafting the biggest RSML release so far, little by little.

The move from mkdocs to DocFX has proved to complete a lot of tasks that were previously ours to get done, giving us time to focus on what truly matters.