Ultimate guide to documenting components using docz
Writing documentation is necessary but is often left as an after thought and only completed near the end of the software development life cycle. In my experience It may be the last thing I do once I have finished building a feature. Things I may document include how to get started in life contributing to a repository, document properties of the components and api endpoints. Waiting to the end of the development cycle is not ideal because at times with best intentions I might never get around to actually writing the documentation.
What if I said you could build your React documentation at exactly the same time as you build that feature. Let's talk about Docz the solution to all my documentation problems.
Click here to view live demo of drum machine.
Click here to view live demo of the Docz site.
What is docz?
Docz is an Open Source, zero config, easy to customize static site generator with the goal of removing the pains of creating documentation websites.
I am able to build React components alongside my documentation website, and have the documentation site live update in real time as I add new props to said React component. Sounds amazing right! This is where Docz shines with the power of mdx and React docz can pull in a live React component.
How does it work?
Leveraging the power of Gatsby, docz builds a mobile first, SEO friendly static website along-side your projects.
- You write a markdown file
- point docz to a React component
- the React component should have comments in the interface and type declarations as seen below
- docz renders an HTML page for it in a separate website.
Docz renders components live with MDX and has TypeScript support, to mention two of my favourite features.
Instead I will guide you through how I integrated docz into my side project Machine a drum machine built with React.
Click here to view live demo.
I've always wanted to build a site to document my React components but I always thought I didn't have enough time... enter docz.
What do I want to document?
As a developer working in a team I want to:
- describe the interface of a React component
- what props the component has
- describe correct usage or integration patterns
Installing docz in a monorepo
I have a monorepo with a React client-side only app (SPA) and an Apollo GraphQL backend. All is driven by Yarn workspaces.
I had to decide between two integration choices...
First decision I needed to make was do I want integrate docz within my existing client folder.
This possible with docz, docz will find all mdx files existing in the project and render a website from this. This would allow me to follow React feature based architecture pattern by having the component, the mdx file, the unit test all in one folder, like this:
Click here to view tiny example on GitHub.
I could choose to create a third folder call it
documentation and have a standalone website which I tell Yarn Workspaces about.
Click here to view on GitHub.
Option B is the what I went with. I like the separation of concerns, this is matter of personal taste you go with what you like. It also made it easier to deploy in the monorepo context on Netlify.
create package.json with Yarn
Install docz and react and react-dom both @ version 16.8.0 as per the docz docs. I also included rimraf so I can delete the compiled .docz build directly from time to time.
- I set docz to run on port 3002 and 3003 as the React client is already using port 3000
- you may notice I have also installed @nejcm/docz-theme-extended, its great do this.
As I have monorepo, I created scripts to run docz from the ROOT directory of the entire project.
I made one script to correspond to each script in docz folder. I am use
concurrently to run all scripts at the same time to have all services running at the same time.
In the root of
documentation folder create a doczrc.js configuration file.
- enable typescript features
- customize theme, set to dark mode by default, add dark and light logo
- configure the side menu with Groups and sube nav items
For brevity I have emptied some of the objects, you can see a completed version here on GitHub.
I wanted to extend the default style of the frontend and I found a really neat project docz-theme-extended.
Install @nejcm docz-theme-extended and configure the gatsby config like this:
create a gatsby config file
With all the above correctly configured I have this to show for it:
Click here to view live demo.
Document first component
Recall that we have a monorepo, with 3 folders
Docz shines here, as we can now reach into any of these folders and bring React components into it's context for documentation.
MDX is awesome, having a live component in a webpage that you can update the props and see the changes reflect immediately is great DX, I love it.
Notice in the MDX file below I have meta data,
- name (name of component)
- route (builds the path in address bar)
- parent (tel docz under which group to place the nav item)
- menu (tel docs under which drop-down nav to place the menu item)
Notice my imports, I am importing
Props. Secondly I am reaching into the client folder and including my button component into the documentation site.
Now any changes I make to the client will be reflected immediately in the documentation website.
Deploying to Netlify
I have 3 services in this monorepo now, the Machine (client), the documentation website, both are deployed to Netlify and the server to Heroku.
Configure Netlify deployment context to point to the documentation folder and run the correct build command.
Run the build command to create a production build of docz. Docz will create a
.docz and in my case place a
public folder inside which is what users will see.
I highly recommend that you use the Netlify CLI so you can test you production builds locally.
Docz site deployed
This one self inflicted issue I had was React version mismatch. The client was already running on email@example.com, being a Yarn monorepo the docz documentation site had installed firstname.lastname@example.org docz ran into version mismatch error. I simply had to lower the version of react on the client.
The team at docz have done an amazing job of simplifying the process of building a documentation site. All the Gatsby complexity has been abstracted away and docz have exposed 3 commands to build and deploy your site.
Thank you docz, whether you are building single page apps, websites or apis docz is easily integrated int your workflow give it a try 🚀.