Creating Documentation

Creating documentation using Storybook and Sphinx

We can also take the resulting renderings and put them into our documentation. To do this, we first export Storybook as a static application, then include those files with our documentation.

To compile the static version, we run the build-storybook script.

$ npm run build-storybook

This creates a new directory src/storybook-static and places the HTML and JavaScript files in it. To incorporate this into the Sphinx documentation, we’ll use a symbolic link and add it to the index.rst file in docs. The advantage of this link is that we do not need to change default output directories or repeatedly copy files. We set up the link once, and then the documentation uses the right files from then on. Since the included files have already been converted to HTML, and JavaScript, they should go in the _static subdirectory. We can change to the docs/source/_static directory and create the symbolic link. Of course, the exact path to the source directory will depend on where we start. For example, on your local machine, it can be:

$ cd react-examples/docs/source/_static
$ ln -s ../../../storybook-static

Note: Symlinks are not supported in Windows, so we need to re-copy the whole directory every time it is rebuilt.

Putting a link in index.rs involves simply writing the HTML link in place with 'Storybook stylesheet <_static/storybook-static/index.html>'_. Don’t forget the trailing underscore. It’s part of the syntax that indicates that we’re creating a link. Next, we re-create the Sphinx documentation with make html from the docs directory.

Try it yourself

Note: All the installations and steps are already done on this platform.

1. Press “Run” in the widget below.

2. Open the link given below, and you will see the Sphinx documentation. We have added Storybook to it.

3. Open the Storybook stylesheet link under the “Styling” section to see a static, pre-built version of the Storybook style sheet.see storybook.