Making the doc available

A project log for DIY Power for all - OwnTech

A fully open-source digital power electronics technology framework for fast prototyping switch-mode power supplies

luiz-villaLuiz Villa 10/09/2022 at 13:290 Comments

 Documentation is the beacon that lights the path of an open source project. As such is should be visible and easy to find. But have you ever tried to actually build the documentation? That is exactly what I tasked myself to do and this is my journey.

I have started thinking of the high level requirements : what would be a good way of documenting the project as a whole ?

Requirements :

First things first: aggregating content

We use the wikis integrated into our gitlab forge as a means to document our work. It has several advantages, such as support for some specific markdown perks (more details here).

Building on the work from Guillaume and Jean, I aggregated the content that explains the hardware for both spin and twist in their respective gitlab wikis.

The SPIN and TWIST wikis at gitlab
A view of the SPIN and TWIST wikis at gitlab

Once the content is aggregate comes the question: how can people find it?  

How to spread the word: finding parsing methods for the content

Having the documentation in markdown is a great advantage: there are many ways to parse it and make it available online. However, there is also a great challenge: markdown flavors are a dime a dozen.

Choosing a parsing method requires supporting the chosen markdown flavor and automatically deploying it a website. The strategy was two-fold:

We will simplify our story and give you our two latest attempts to reach this goal.

The Docsify attempt

When we came across docsify we though that it would be a great tool for automatically parsing our wikis.

OwnDocs docsify landing page
The docsify landing page - Full of promise!

However, like all other methods, it does not support gitlab flavored markdown. We though it would still be worth the trouble and went on with the idea that we could adapt our work just enough to use it well.

And so we did. Wiki by wiki we took the pain to correctly verify that evything could parse and show up nicely on our docsify instance.

Markdown in three different formats and not parsing in docsify
The markdown house of cards

And after everything was said and done, we were ready to deploy!

The server incident

Here we were happy to achieve a great documentation which we were ready to transform into HTML and deploy. But that feature is not supported by Docsify. And our server service provider does not allow us to deploy anything but static HTML pages to our website.

We find this out, of course, on october 9th, a few hours before the hackaday deadline.

So, what now?

Docsaurus as a solution

Armed with a greater resolve and shorter time, here we found ourselves asking what solution can we deploy that will take all of our work AND render a static HTLM page?

After hunting for clues online, we came across Docusaurus.

Docsaurus let's go!
Getting started at 3AM? Yes, sure, what could go wrong?

Docusaurus was a very pleasant surprise! Easy to understand, it was a short stretch from the work we did with docsify, giving us an automatic sidebar and the means of getting as much information from the SPIN and TWIST wikis as possible with no re-work.

OwnDocs finally online!
The online version of OwnDocs

You can now find the first version of our hardware documentation aggregated on our website:  

Happy reading!