[WIP] Refactoring documentation to use Nacara

[64J0]

Description:

With this PR, I'm proposing the substitution of Fornax by Nacara as the static site generator for the Saturn docs pages (cc @MangelMaxime).

During my tests, I was able to reuse most of the pages already written with not much changes, except for one parameter (the layout).

Some points of consideration related to this proposed change, are:

• This tool uses Node.js. ~If we're going to really use it, I can create another PR (or even tackle it in this one), changing the CI job that builds the documentation~ (done).
• I'm not sure how straightforward it is to replace the current configuration in the gh-pages branch (supposing the blog is attached to it). But I'll try my best to replicate what we currently have in this branch here.
• ~Re-write the API Reference content using markdown~ (done).
• ~Fix the commands broken ("Docs")~ (done).

---

Other ideas to consider in the future are:

• [ ] Use other themes.
• [ ] Add more stylish features.

---

Continuation of #357.

How to test it?

Nacara requirements:

• Node.js 12.20, 14.14, or 16.0

cd docs/
npm run watch

# open localhost:8080 in your browser

After testing the project, one can use this section of the Nacara documentation to understand how to build and expose the project: https://mangelmaxime.github.io/Nacara/nacara/guides/deploy-your-site.html.

[64J0]

Each new commit decrease the quantity of changes since I'm removing a bunch of HTML stuff and using MD instead.

[64J0]

Finished the translation of the references.

[64J0]

I think the PR is done, but I'm not sure how to test locally. Using GH pages to host the built code does not look good, at least in my local repository: https://64j0.github.io/Saturn/. But, if I serve it through npm run watch the project looks beautiful.

I added some questions in this topic to the Issue mentioned before in this PR timeline.

---

GIF showing the output when running with npm run watch:

[64J0]

Just discovered that Nacara is going to be deprecated in the future in favor of another project. Due to it, I'm going to consider other possibilities:

• https://github.com/MangelMaxime/eleventy-layout-nacara

This is a relatively new project, and it does not have a documentation created yet. Maybe we can use it and keep the .fsx files as they are, but I'm not sure how this project will behave in the long run. Until now, it has a single contributor, and I'm not aware of anyone using it in the way it is right now.

• https://github.com/facebook/docusaurus

A battle-tested project, with some years of development so far. AFAIK, it is still maintained by Facebook, which is cool. It has a bunch of contributors, and a mature user base. One problem related to this project is that we would need to translate all the current .fsx files to .md. It does not seem too much work, just mentioning it here because this is a point where we would turn less F# and more MD.

What do you think @cartermp ?

[64J0]

Update, I was able to make the documentation look beautiful in my project!

It was a matter of fine-tuning the nacara.config.js file: https://64j0.github.io/Saturn/

[cartermp]

I really like the updated look in your link. Will give this a look-over!

[Krzysztof-Cieslak]

That looks great. How are all those .md files generated?

[64J0]

That looks great. How are all those .md files generated?

@Krzysztof-Cieslak in current implementation with Fornax they are generated automatically in the build process from the code/comments, right? I was not able to implement a similar feature, unfortunately. For this PR, the process was manual.

I got the HTML files from the current gh-pages branch, was looking at the information we have in the docs page, and "translating" it to MD syntax. I was not able to replicate everything as it is in the HTML files, due to limitations in markdown (multi-line tables, for example).

In this scenario I used a different approach, avoiding the table and using another structure to present the same information. Something like this:

---

• Type: SomeType

  Description: Some multi-line description.

  More description line.

  Example:

  # comment
  printfn "Code example"

[64J0]

Tested locally, and it seems to be ready to be reviewed. I removed the [WIP] from the PR title.

[Krzysztof-Cieslak]

In current implementation with Fornax they are generated automatically in the build process from the code/comments, right?

Yes, that is correct, indeed.

I was not able to implement a similar feature, unfortunately.

I am a bit worried about depending on manual updates for updating API reference documentation - this greatly increases the chance of things being out of sync/people forgetting to update docs in both places etc.

Maybe we could generate those .md files using a standalone (i.e. not depending on Fornax) script/tool? The main heavy lifting is done by F#.Formatting dependency. I believe apirefloader.fsx should have code for generating structured data... and generating .md files is just a matter of string concatenation.

Similarly, we could do the same for generating Lunr search index (lunr.fsx in the old implementation) which powered search capability [which seems to be not there in the new implementation].

[64J0]

I am a bit worried about depending on manual updates for updating API reference documentation - this greatly increases the chance of things being out of sync/people forgetting to update docs in both places etc.

Maybe we could generate those .md files using a standalone (i.e. not depending on Fornax) script/tool? The main heavy lifting is done by F#.Formatting dependency. I believe apirefloader.fsx should have code for generating structured data... and generating .md files is just a matter of string concatenation.

Similarly, we could do the same for generating Lunr search index (lunr.fsx in the old implementation) which powered search capability [which seems to be not there in the new implementation].

All right, thanks for pointing it, I'll take a look at those files to understand it better.

[MangelMaxime]

I am a bit worried about depending on manual updates for updating API reference documentation - this greatly increases the chance of things being out of sync/people forgetting to update docs in both places etc.

Maybe we could generate those .md files using a standalone (i.e. not depending on Fornax) script/tool? The main heavy lifting is done by F#.Formatting dependency. I believe apirefloader.fsx should have code for generating structured data... and generating .md files is just a matter of string concatenation.

I agree generating it automatically is better.

Nacara has a dotnet tool to generate F# API: https://mangelmaxime.github.io/Nacara/nacara-apigen/introduction.html

However it is in a really early state.

It is used for generating Fable.Promise API doc

---

Things to know too is that Nacara is being completely rewritten to work on top of Eleventy. This will allow me to focus on F# specific features + just providing the layout stuff. I will not be responsible anymore for providing template support, watch mode, etc.

I already have the port working in a repo and I am currently working on the documentation and migration guide. According to my test the migration should be smooth:

• Adapting the layout property of the docs files
• Exploding the nacara.config.js file into several Eleventy Data file (more or less copy/paste)

When ready I will revisit this issue/project to help in the migration.

[64J0]

I decided to not keep going with this effort, to focus in other activities. Due to it, I'm closing this PR.