WIP: propose a framework for documentation

[frallax]

A common problem for SW projects is how to create
documentation (both user oriented, describing how
to use the tool, and developer oriented, describing
concepts such as “design specifications”, “architecture
descriptions”, "adrs").

This commit aims to show how we could create developer
oriented documentation. It add a framework that picks the
existing adrs markdown files, and deploy them to a static
webpage.

Benefits of the proposed approach:

• documentation is in the same repo as the code (no
  risk of spreading it in different tools/repos);

• documentation is versioned in the same way as code;

• documentation can be still be read/visualized on github,
  but it can also be deployed locally on the machine
  where the repo has been cloned, or deployed to github
  page or similar;

• the markdown files representing the documentation
  (in this case the adr) are not modified;

• this approach could be common between multiple
  projects under the eclipse-cdt-cloud group;

The same approach could be used to generate user oriented
documentation, but it is outside the scope of this commit.

See the README file to get going.

Signed-off-by: Francesco Robino francesco.robino@ericsson.com

[bhufmann]

I tried to follow the instructions I get a message that it requires node 14. The project currently still requires only node 12.

> npm install
...
> gatsby develop

 ERROR 

Gatsby requires Node.js 14.15.0 or higher (you have v12.18.3).
Upgrade Node to the latest stable release: https://gatsby.dev/upgrading-node-js

Is there a way to make it work with node 12?

[bhufmann]

The content of the documentation will have to be created (User Guides, Developer Guides etc), when if we go further with this documentation.

I'm not fully clear how to deploy it so that people in open source can see the webpage. I wonder if it could run as part of the Github pages of this project. Any suggestion for this?

[bhufmann]

Is there a way to make it work with node 12?

Maybe when upgrading to latest Theia, which is supposed to work with node 14, this is not an issue anymore.

[hoangphamEclipse]

@frallax Is there any update regarding this PR?

[frallax]

Hi @hoangphamEclipse,

let me summarize what has happened:

• the above questions from @bhufmann has been addressed:
  • the npm issue is not an issue
  • yes, we can deploy on github pages if we want to (using github actions or travisCI or similar)

What I am working on lately is:

• fixing the layout of the page (especially the sidebar, and the logic to generate it)

Something that still has to be decided is:

• do we want to use front matter in the md files that will generate the documentation?
  • currently the ADRs (the only documentation handled) are not using front matter. This makes the "page generation" a bit more cumbersome because it is based on file names and folders. But it keeps the md files clean.
  • I would prefer that we use front matter because it would simplify the logic to generate pages, with the caveat that the md files are "more dirty". But that is just my opinion and should be discussed.
• do we want to break this pull requests in "smaller commits"?
• what content do we want on the page?

[hoangphamEclipse]

Thank you @frallax for the update.

[frallax]

Updates:

• added a new foldable sidebar (looks cooler than the bullet points)
• the new sidebar structure builds automatically based on the path of the identified md files
  • note: as of now the identified md files (i.e. the md files used to create the page) are only the ones in the doc/adr folder or the ones in the doc/web-doc/src/pages

This update does not address the questions listed in a comment above. Those are still open for discussion.

Why did I do this? It is just to proof that if we want we can generate documentation (and a sidebar to browse it) automatically without having to use front matter in md files. However, I am still thinking that using front matter in md files could be beneficial.

[Rodrigoplp-work]

Excellent proposal! I can't wait to have a site for visualizing documentation.

But I advise against using GatsbyJS because:

• The framework is dated. It was the best way (IMO) to build static sites when it was released, but many of its features and solutions are now outdated;
• Hard to maintain: Gatsby has been through some heavy breaking changes in the past (with versions 2.0.0 and 3.0.0) that required extensive refactoring. It is now already on version 5 (this PR uses v. 4);
• Large code base: Gatsby relies on plugins developed by its community to do what it does, like converting markdown files to html. Some of these plugins are large and outdated, causing the code base for a simple static site to be quite large in comparison to other frameworks available today;
• Fading community support: Gatsby was great because the JS community got highly involved when it was released. Plugins, discussions and support abounded. Today other frameworks are receiving more attention.

Due to these reasons I propose we adopt a different Framework for this task: SvelteKit. I created PR #896 for you to consider as a replacement for this one.

[marco-miller]

@Rodrigoplp-work, you're welcome I think to formalize your review for this specific PR. I mean, by means of using Review changes, then Submit(ting) your review per above. Thanks!

[Rodrigoplp-work]

Excellent proposal! I can't wait to have a site for visualizing documentation.

But I advise against using GatsbyJS because:

• The framework is dated. It was the best way (IMO) to build static sites when it was released, but many of its features and solutions are now outdated;
• Hard to maintain: Gatsby has been through some heavy breaking changes in the past (with versions 2.0.0 and 3.0.0) that required extensive refactoring. It is now already on version 5 (this PR uses v. 4);
• Large code base: Gatsby relies on plugins developed by its community to do what it does, like converting markdown files to html. Some of these plugins are large and outdated, causing the code base for a simple static site to be quite large in comparison to other frameworks available today;
• Fading community support: Gatsby was great because the JS community got highly involved when it was released. Plugins, discussions and support abounded. Today other frameworks are receiving more attention.

Due to these reasons I propose we adopt a different Framework for this task: SvelteKit. I created PR #896 for you to consider as a replacement for this one.