Skip to content

docs: WCL docs new workspace

Warren Gifford requested to merge fj/wcl-docs-workspace into main

Created by: 5h1rU

Status

How to run:

  1. Pull the branch fj/wcl-docs-workspace
  2. run the command yarn wcldocs:start
  3. a new browser window will be prompted pointing to http://localhost:3000
  4. Done.

Description

The initial plan was to have a skeleton ready to start adding docs. IMO, Having docs from the beginning is more valuable than investing time in automating a tool for docs that will not be modified often. This version is almost ready to deploy. I'm sure it achieves all the goals planned for this iteration.

WCL components are not strictly following the typedocs guidelines. It derives in a complicated situation for automating the outcome of the docs. The comment blocks extraction from typescript was abnormal. Some components were missing props. Others shown props coming from the react codebase and many different situations were hard to predict.

I decided to go with an intermediate solution, using the extraction tools for every component and adding the missing information manually. We don't have a lot of components in WCL, and we don't expect to grow these libraries every day, so I'm convinced that doing a bit of manual work here is not bad at all. Besides, I completed the docs for the whole set of components (excluding the navigation bar since this is not a WCL component).

Hooks are documented as well, but the current docs need to be polished (For the reason mentioned above).

For the sections that aren't implemented yet, the way to edit is straightforward. Files are already there and work like any other markdown file. In case that you need any guide, here is the Docusaurus official docs.

The subsequent steps will normalize all the comment blocks and follow strict guidelines for writing good code comments. Only then can we rely on automation tools to have high-quality docs.

Outstanding work

  • These sections are missing: add the proper docs to each file. - Nothing to do on the engineering side.
  • Visual design: Implement the design.
  • Deployment pipeline: Make sure Netlify is being deployed with each WCL change. You can see the issues and all the references in the project board

Merge request reports