Keeping Your Documentation Up-to-Date with Bit and GitHub
By: Fernando Doglio
Tags: JavaScript, Frontend, Nodejs, Front End Development, Web Development

Setting up the right project structure

One of the benefits of automation, is that you don’t have to worry about manually doing a particular task. But for this to happen, you have to favor certain configurations or folder structures. And in our case, the same thing happens; we’ll need to follow certain rules for this automation to take place.

The folder structure

You can customize the following structure however you like, as long as you then update the rest of the examples to accommodate for that change.

However, the folder structure I went with for my sample project is the following:

The .github folder will be created for us by Github or we can add it manually, that’s not a problem. Here is where the workflow file for our Github action will live.

folder will be created for us by Github or we can add it manually, that’s not a problem. Here is where the workflow file for our Github action will live. The components folder is where we’ll have our components “imported” from Bit. You can really have them anywhere, I’m just using this as an example.

folder is where we’ll have our components “imported” from Bit. You can really have them anywhere, I’m just using this as an example. The examples folder is where we’ll save our snippets and their corresponding test files (inside the examples/tests folder).

folder is where we’ll save our snippets and their corresponding test files (inside the folder). And finally, the last interesting bit, is the file called test-output-parser.js which will take the output of our tests, parse it and figure out which files to update based on the outcome.

Setting the tests for our snippets

I know what you’re thinking: who writes tests for their snippets? And I get it, if you only have 2 or 3 snippets, there is really no point for that. But then again, if you only have 3 snippets, then there is no point for you to be doing any of what I’m showing here.

However, if you’re building something massive, which has very rich documentation, you could be looking at tens or even hundreds of code snippets, showing all the potential ways of interacting with your project. And if that is the case, trust me, you’ll want to automatically check if they’re still valid or not after the component they depend on gets updated.

So, for each snippet you have, write at least one test that, and make sure they look like this:

A couple of points:

I’m using mocha for my tests, if you’re using something else, you’ll need to adapt the rest of the examples as well. Notice how the nested describe is mentioning the name of the file where the snippet is coming from. This is required, because we need a way to understand which file this test is testing (and there is really no other way of doing this).

This should be enough to make sure our snippets are still valid.

Creating the Github Action

With our folder structure in place and our tests written, we need to make sure that once we merge a PR, we execute them, and parse their output.

Here is where GitHub comes into play. We can do this by going to our repository and clicking the Actions tab:

Click on the Create new workflow button and pick any of the templates available, we’ll replace their content in a second anyway.

Essentially, we want a workflow that gets triggered on a Push action to our main branch. This is because I’m assuming you’re not allowing developers to directly push to your main , instead only PRs will be created against it and the only actual Push will be done by Github when we merge it. Sadly there are no merge triggers right now, so we can’t really use that event here.

The content of our workflow file looks like this:

There is some boilerplate code in there, but the main things to look at are:

In line 16 we’re setting Node’s version to be 14. We can add a list of versions if we want our tests to run with different ones just in case.

Line 26 runs npm install which makes sure we have every dependency required for our project to run the tests. This is also important, because if your PR only updated the package’s version inside package.json , then this will install that version.

which makes sure we have every dependency required for our project to run the tests. This is also important, because if your PR only updated the package’s version inside , then this will install that version. Line 27 runs the tests, parses the output and updates all needed files. This one line takes care of everything (we’ll take a look at the JS file in a minute).

Lines 28–40 take care of updating the branch, since we’ve potentially made changes to some files (the snippets that are deprecated), we’ll need to create a new commit (hence the commit message and the credentials shown in there).

This workflow will run every time you merge a PR. They may be PRs created by Bit or PRs created by other users. Either way, every time it runs, you’ll see an output like the following inside the logs screen:

Notice how in this particular scenario, the examples/sample1.js file got updated with the deprecation warning.

Also, in case you didn’t notice it, the command we’re using to run our tests is: ./node_modules/mocha/bin/mocha examples/tests -R json

We’re having to use the local version of mocha that gets installed as a dependency, and we’re using the JSON reporter, this will simplify the task of parsing the output. Which funny enough, is the next topic to cover.

Parsing the output of the tests

To make things simpler, we’re using Mocha’s JSON reporter, which gives all the information we need in a format that Node.js can easily interpret.

Our script will have to:

Look for errors reported For each one, we’ll parse the message extracting the filename Open the file, and add the deprecation warning at the top (only if it doesn’t have it already).

And here is the code that takes care of that:

The script is very straightforward, it captures the JSON received as part of the argv array and parses it. If there is anything inside the errors element, then we’ll iterate over those elements and perform the tasks I already mentioned.

Nothing else, the content of the files will be updated only if their corresponding tests failed and if they don’t already have the warning inside them (this is to make sure we don’t keep adding warning after warning with subsequent PRs).

How do we know if the workflow changed anything?

The easiest way to check for this, is to look at your repository’s list of files. If the workflow was executed and some tests failed, then it should’ve made the changes and saved them with the following message: “ci: Automatic Deprecation Warning added”

So just look for that in the list of files, like this:

As I mentioned before, you can extend this workflow even further and add the ability to notify you through the channels you need (i.e Slack, email or whatever you use).

Using the code snippets directly from Github

The final step we’ve not talked about yet, is the one about including the code snippets directly from GitHub. This will cause your documentation to be automatically updated with the deprecation warning the moment it is added.

And because you also might want to keep documentation and implementation as two separate projects, this tool might be the best fit for your needs: Gist-it

All you have to do to include the following script tag wherever you want your snippet to appear:

<script src="http://gist-it.appspot.com/URL-TO-SNIPPET-FILE"></script>

So, the following page:

Gets rendered like this:

You don’t really have to worry about the snippet, it will automatically update with any new change published to Github and as you can see, it already comes with syntax highlighting. Notice the first line of the code: the deprecation warning is already in place.