feature: Create MDBOOK documentation for Signal K server.

[panaaj]

Create configuration and source documents for Signal K server documentation that is available as part of the a running server and will be available at https://demo.signalk.org/.

Initial document source is the migration of existing .md documents into the src folder.
An index has been created and the existing document content re-factored to fit the index structure.

This inital structure will serve as the basis for future refinement, and editing as required.

The HTML documentation is generated by running npm run build:docs and the resulting files are at docs/built/ mounted at /documentation/. The documentation is accessed via the Admin UI Documentation.

Note: the documentation generation requires that docker be available.

[tkurki]

Wow you've created a lot of new content here!

Now that I've looked into this: I think we have different kinds of documentation:

1. "Server User Manuel" - explaining how the server works and how it is configured
2. "Developer Documentation" - plugins, webapps, providers
3. Release notes/changelogs, v2 documentation
4. "Use cases / Features / How tos" - practical use cases, like using the server as 0183 multiplexer and converter, explaining what the use case is and then step by step guides on how to configure it, like the pdf here

This PR puts 1 & 2 & 3 together, into standalone manual format. I am starting to think that developer docs should be separate, as they add clutter & confusion for the end users. Having developer documentation embedded in the admin ui is way less important than having it easily discoverable on the github site / from the readme.

How tos are also a bit separate, but closer to user manual.

While mdbook is a tidy format having it totally outside the server admin UI strikes me as a bit confusing. We could also embed some documentation, like changelogs and How tos, directly in the admin UI. We used to have changelog rendered with react-markdown, when it was committed into the repo.

Thoughts?

[panaaj]

I don't disagree that the different types of documentation could / should be hosted in different places but that said part of the motivation behind this PR was the number of queries and support requests where the answer was documented and it wasn't obvious where that was.

I believe there is value in having a central place where all the docs can be found. This is the initial aggregation.

Is there a case for having all the information available as part of the installation, more a reference than a manual?

What ever the answer I do think there is value in one set of documentation.

[tkurki]

@mpvader I converted the anchoralarm feature howto to .md and included it in the Server Guide in this PR. You can have a look with docker run --rm -p 3000:3000 signalk/signalk-server:documentation:

@panaaj already added Freeboard as one more way to use anchor alarms.

[mpvader]

Nice, I’ll have a look in coming few days

[mpvader]

Hey @tkurki and @panaaj, I finally had a good look, and this is really nice and promising!

My comments:

• for a large section like the anchor alarm, it would be nice if there is some sort of in-page navigation? Or, even better, make the content such that mdbooks (?? I'm sorry, didn't look into the used tooling at all, will do soon) recognises all the sections on the anchor-alarm document, enumerates them in the index on the left, hides that part normally and only unfolds it once entering the page? Anyway: probably best if mdbooks supports something like that, anything, and lets then go with that rather than customising too far.
• rereading that anchor page content, I'd see various things that I'd like to change; which I'll do myself.
• perhaps find a better word for Server Guide ? Actually, if we keep it like this: all documentation only shows up if you navigate away from the admin ui, then lets move that Open API link also into the server guide. And then clicking the Documentation link just takes the user straight into this new docs section.
• what is the plan with duplicate content with the readme? Such as the commandline options.
• the menu is a bit strange, for example in the installation section there is lots of interesting content which, if you go by the navigation menu on the left, you'll never find. Also the navigation section says "Installation", but in the content I can't find that chapter name anywhere.
• Clicking help and support on the left makes the screen move a bit, the term "Installation" disappears. Compare first to second screenshot:

First screenshot:

Second screenshot:

[mpvader]

This issue at mdBook seems to describe what I’m looking for wrt in page navigation, as well as offer a few solutions:

rust-lang/mdBook#1523

[panaaj]

• for a large section like the anchor alarm, it would be nice if there is some sort of in-page navigation? Or, even better, make the content such that mdbooks (?? I'm sorry, didn't look into the used tooling at all, will do soon) recognises all the sections on the anchor-alarm document, enumerates them in the index on the left, hides that part normally and only unfolds it once entering the page? Anyway: probably best if mdbooks supports something like that, anything, and lets then go with that rather than customising too far.

Unfortunately it appears that MDBOOKS does not support links to page sections from the SUMMARY.md (left menu), adding entries withlinks to page sections fails the build process.

For now I have manually added a Contents section to the beginning of the Anchor Alarm page with links to the major sections.

[panaaj]

• Clicking help and support on the left makes the screen move a bit, the term "Installation" disappears. Compare first to second screenshot:

The MDBOOK behaviour seems to be "move the selected entry in the left menu to the center".

I assume that is what you are referring to as the navigation to the content is correct.

[panaaj]

• perhaps find a better word for Server Guide ? Actually, if we keep it like this: all documentation only shows up if you navigate away from the admin ui, then lets move that Open API link also into the server guide. And then clicking the Documentation link just takes the user straight into this new docs section.
• what is the plan with duplicate content with the readme? Such as the commandline options.

From my perspective this will depend on how we treat this documentation.

Initially the intent was to have one place to go for Signal K server documentation, not necessarily a "Help" document for the server. Exisiting documentation is "scattered around" and it was clear from the questions asked in the Slack channel and discussions that the exisiting information that answered their question was not easily found or people didn't know where to look.

The content included in the MDBOOK covers a broad range of topics and could easily serve different puposes, so there are options about how it is managed and published, which no doubt there will be discussions about.

As for the README... I feel that is related to the repository contents rather than "operating the product" (in this case Signal K server). There will certainly be overlapping content but this should link to the relevant documentation in the MDBOOK to avoid duplication.

Clearly there is still a journey to travel here because there are options, all of which will have merit.

[mpvader]

Initially the intent was to have one place to go for Signal K server documentation,
…
The content included in the MDBOOK covers a broad range of topics and could easily serve different puposes

understood; and having it all together is a major improvement. In my opinion the term used for the menu entry, “Documentation”, is great and covers it all.

README

agreed. So content will need to be removed there.

In page navigation

I noticed your added TOC on the anchor page; nice and simple solution!

[tkurki]

A sidenote maybe, but we should look into gwnerating plugin api documenation off the ts files/embed the documentation there and use https://www.npmjs.com/package/typedoc-plugin-markdown to generate md to be embedded here

[tkurki]

Now deployed at https://docs-signalk-io.fly.dev/

[tkurki]

I looked into generating server API docs with typedoc markdown plugin: the problem with that is that mdbook does not generate html for .md files that are not in SUMMARY.md so the subpages that typedoc links to are not there. Including all of them in SUMMARY.md is not feasible, so this would need more than trivial tweaking.

However I think we should move towards api docs off the .ts files in one way or another, but that need not be part of this PR.

[tkurki]

Now that the mdbook links back to the admin UI I think we should move towards getting this thing out the door: not creating & tweaking content, but resolving the issues that relate to coherence: how does the new documentation format work together with the README and previous documentation addresses?

• replace duplicate sections in repo root README with links to either deployed documentation at demo.signalk.org (or create docs.signalk.org, but then also the spec docs should be accessible there?) or the md files in their new locations
• add placeholder files that point to the new location for the most prominent files, like SERVERPLUGINS.md and raspberry installation so that they don't simply disappear
• decide on the navigation in the sidebar: What if we pull OpenApi from under Documentation to the top level and link Documentation to the mdbook?

What else?

[panaaj]

What should we do with SEATALK (GPIO).md and other outliers?

[mpvader]

Nice! I’d stick with demo.signalk.org.

[panaaj]

I agree that demo.signalk.org is a better choice for the reason that the docs in question are related to the server.

I would expect to find the spec documents at docs.signalk.org.

The other option is to have something like docs.server.signalk.org.

[tkurki]

Seatalk goes under Configuration, 3.1 Seatalk I think. The logic being that there could or should be docs there for the different connection types, nobody's just written them yet, and for discoverability.

What else are we missing?

[tkurki]

Reorganised sidebar like so

[mpvader]

What is so important in that OpenAPI link? Can’t that be linked from one of the dev docs? Maybe a page that explains what it is?

as a user, I clicked it a few times, and then was surprised to be taken away from admin ui to some internet page

[tkurki]

Yeah, I know the switch to another UI is jarring. Maybe I am too stuck on the idea is that I don't want the API descriptions to be buried under clicks and scrolls.

Just for the record: it is not an internet page, but served by the server. Swagger UI is a component that renders the UI that you see: it takes an OpenApi API description of a REST/HTTP API, lists the methods and the structure of their parameters and return values. See for example https://demo.signalk.io/doc/openapi/?urls.primaryName=course

The problem it solves is that now for example the way anchorwatch works is not very well documented: what HTTP path to use, what parameters to use, what to expect in return, how to retrieve anchor data. SK v1 created a universal data model, but there is no clear way to document a specific use case. The idea going forward is that we can create these modular, smallish APIs that you can use for the different use cases, instead of figuring out by trial and monitoring how something is done by a specific plugin, like anchor watch.

[mpvader]

ok yes, I see it now, its not some page somewhere on the internet. Fooled me. I see the value for a developer, but not for the average user of the admin ui.

In the end, where that link goes (or if it stays where it is now I mean) doesn't matter much, such average user might click it once, maybe twice, and then never again.

[tkurki]

Sidebar navigation opens blank on my ios chrome, probably related to the sk navigation as it works on stock mdbook rust docs.

[panaaj]

See a similar issue on my Android phone.

[tkurki]

I rebased on master and hopefully did not mess up anything resolving the conflicts.

I think this is good enougn to merge, we can tweak the content later and add further improvements like generating and not writing the api docs by hand etc. Also in-repo md:s that may need fixing are easily done off master.

[panaaj]

I rebased on master and hopefully did not mess up anything resolving the conflicts.

I had a scan and fixed a truncated sentence as well as a few stray punctuation marks.
It is good to go.

[tkurki]

All good here, but I really want to start producing apidocs off the source files after this is merged.