nimbus-libs-site/README.md

Nimbus Docs Suite

This a documentation generator for Nimbus Libraries at nimbus-libs.status.im. It's made to auto-regenerate from master on all the repos you want documented but at the same time supports custom content and theming. It uses Vuepress behind the scenes.

Dependencies

You need:

• a fairly recent version of NodeJS (Windows Version)
• yarn
• vuepress globally installed or locally but for use via npx.

Building

git clone https://github.com/status-im/nimbus-docs-suite
cd nimbus-docs-suite
cd docgen && yarn install
vuepress build

The results of the build process will be in docgen/.vuepress/dist.

Note: You might have to run vuepress build twice, because the first run writes the temporary MD files, while the second run builds HTML from them. We're working on making all that happen in one go and there's a pending issue in Vuepress.

What's behind the build command

When you run vuepress build, the builder:

• reads config.json for the repos it should process.
• uses the information there to build the homepage by constructing library cards for each repo.
• for every repo with update: true, grabs their README file and strips their header and footer (above Introduction and below Contributing).
• changes image URLs to match raw ones from Github if they are hosted on Github.
• generates frontmatter from the data in config.json, combines it with the README and generates a homepage for each library that way.
• if a Guides folder exists in library's subfolder, it will generate a sidebar navigation from its contents.

The logic responsible for this is in a custom plugin in .vuepress/docgen/plugin.js.

Modifying for your use case

To generate docs in the same way for your own repos:

1. Modify config.json to contain the repos you want process
   • name: slug, URL-friendly name of the project and will be the folder name where the lib's docs are stored
   • label: human readable label and title to be placed at the top of the homepage
   • location: the Github URL of the repo. Must be public. Gitlab and private repos coming soon.
   • update: when false, only generates content from local MD content, does not try to fetch from online master
   • tags: a JS array of tags applying to this lib. Purely aesthetic for now, for the homepage - colored badges will appear next to the lib's name. Add tags into the tags object as desired.
   • description: description for the homepage
   • frontmatter: frontmatter to generate. Key value pairs. Values are same as documented in Vuepress.
2. Also in config.json, set up the start and end separators. This indicates where your README's body begins, and where it ends. Useful for avoiding licensing information or CI badges in your human-readable docs. separators[0] is the starting point of the readme's body, separators[1] is the ending point of the readme's body, and separators[2] lets you specify several separators for start and end if your READMEs across projects aren't standardized. The string of each separator will be exploded with separators[2] and the first of those which is found in a README is considered the valid separator.
3. Modify styles in .vuepress/styles and theme configuration in .vuepress/config.js as desired. Use the Vuepress docs.
4. Run vuepress build inside docgen.

Enhancing the docs further

To further enhance the docs, please consult the Vuepress docs as underneath it's all just a Vue app built by Vuepress.

License

Licensed and distributed under either of

• MIT license: LICENSE-MIT or http://opensource.org/licenses/MIT

or

• Apache License, Version 2.0, (LICENSE-APACHEv2 or http://www.apache.org/licenses/LICENSE-2.0)

at your option. These files may not be copied, modified, or distributed except according to those terms.