HTML Documentation

[cakrit]

This issue is the equivalent of an agile delivery process Epic. The end state for our documentation will be the following:

• The netdata project contains all source files, static content, doc configs and required scripts to build its static html documentation.
• Source files are markdown documents throughout the netdata directory structure
• Static content is images, html fragments, javascripts etc. that reside in a separate directory structure under netdata (htmldoc)
• Required scripts are the code that will be used to validate the consistency of the documentation and to build the site. They will also reside under folder htmldoc
• Doc configs are the files requirements.txt, and runtime.txt that are needed by Netlify to generate the static site at the root directory.
• Netlify is used to generate and publish the site. The main advantage of Netlify over mkdocs is that we are able to specify a custom build command, whereas mkdocs forces us to use either mkdocs or sphinx. We need the custom build command, as the generated files will not be tracked in git.
• Every commit, regardless of whether it is related to code or documentation will trigger the documentation to be built.
• We will have a way to see older versions of the documentation.
• The documentation site will include dynamic links to live demos that enable users to see a referenced chart not only on one of our live demo sites, but also on any of their servers we have kept in our registry (will utilize the registry cookie).
• The HTML site will contain edit page links that lead to the appropriate .md file in the netdata repo

High level list of things that need to happen:

• Incrementally prepare the static site builder, in netdata-doc. The project netdata-doc is temporary.
• Put the static site builder inside netdata, in a separate branch
• Add all required artifacts to the netdata master, update the link in the wiki and lock the wiki to prevent other changes there. From this point onwards all changes are done on the netdata repo.
• Create new site build script, that takes all markdown files from netdata.
• Finalize html site structure (New documentation structure #4321).
• Update the links in the wiki to point to the html site.
• Documentation links sanity checker Documentation links sanity checker #4416

The following will be part of phase 2 and split into separate issues:

• Generate Collectors.md Collectors README and list of plugins/modules #4415
• Modify collector plugin READMEs to align to the README templates Modify collector plugin READMEs to align to the README templates #4438
• Create new static content and update existing static content. We will add several issues on this under the documentation project, such as Add CONTRIBUTING.md #4146 , Add instructions to debug alarm notifications #4319, README template for plugins #4394, Modify collector plugin READMEs to align to the README templates #4438, Write a blog entry about monitoring and performance tuning mysql with netdata #4326 etc.

[ktsaou]

The only problem I see is the images. If we add them into the repo, it will explode in size. This will be problematic, especially since we will also plan to distribute packages with it.

I would suggest to keep all images in a CDN and refer them from documentation.

So, the only images inside the repo, should the images the agent needs.

[cakrit]

Not a bad idea regarding the images, we'll see how big they'll be of course... Do the packages need to contain the images?

[Ferroin]

Alternatively regarding the images, if we can get all of them as uncompressed SVG's, then there shouldn't be any issues with repo size. The size issues with images arise from how git has to handle binary data, but SVG's are text, so they don't demonstrate the same problems.

[cakrit]

With SVGs I can try something like this too: https://www.svgminify.com/

[Ferroin]

While keeping them small is nice, going too far will lead to huge diffs, which will cause the same issues that binary files do, albeit to a lesser degree.

[cakrit]

I've done a lot of work on the 'htmldoc' branch, please take a look at the code under htmldoc and the generated site at https://netdata.netlify.com, as I'll need feedback.

[cakrit]

Site live, all links updated to point to https://docs.netdata.cloud

[ktsaou]

I think the main README.md needs update too. There is a section about documentation.