Skip to main content

Generate documentation

This topic explains how to generate a documentation site from your Rell source code and how to customize it to match your project's branding and requirements.

Overview​

The Chromia CLI provides a built-in command to generate a documentation site from your Rell source code.

  • API documentation automatically generated from Rell source code together with corresponding RellDoc comments in your code.
  • Custom content pages that you can add
  • Customizable styling and branding

Generate a documentation site​

To generate a documentation site, run the following command in your project directory:

chr generate docs-site

You can view the generated site by opening build/docs-site/index.html in your web browser.

The generated site contains JS code to provide a navigation bar. Although you can open the index.html page in your browser, the best experience is achieved by hosting the site on a web server which will enable the navigation.

warning

To view the navigation bar, the generated site needs to run on a web server, see Navigation bar not showing.

Configure document generation​

Document generation is configured in the docs section of your chromia.yml file. Here's an example configuration:

docs:
  title: "My Rell Dapp" # Title of the documentation site
  footerMessage: "© 2024 Copyright MyCompany" # Custom footer message
  customAssets: # Custom assets to include
    - docs-assets/logo.png
    - docs-assets/favicon.ico
  customStyleSheets: # Custom CSS stylesheets
    - docs-assets/custom-styles.css
  additionalContent: # Additional markdown content
    - docs-assets/getting-started.md
    - docs-assets/tutorials/basic-usage.md
  additionalModules:
    - test.doc_module
    - lib.some_lib

Add additional content​

You can add custom content pages to your documentation site by creating Markdown (.md) files and referencing them in the additionalContent section of your configuration.

Example custom content file​

// <title> must match the title property configured in chromia.yml at docs:title

# Dapp <title>

// Content

// <module-1> should be replaced with the name of targeted module

# Module <module-1>

// Content

## Sub-titles are allowed

// Content

# Module <module-2>

// Content

Customize styling​

You can customize the look and feel of your documentation site by creating CSS files and referencing them in the customStyleSheets section of your configuration.

Example custom stylesheet​

:root {
  --primary-color: #4a86e8;
  --secondary-color: #34a853;
  --text-color: #333333;
  --background-color: #e0c7f6;
  --code-background: #a2dbf7;
}

.navbar {
  background-color: var(--primary-color);
}

.sidebar {
  border-right: 1px solid #e16565;
}

Add custom assets​

You can include custom assets such as logos, favicons, and other images by placing them in a directory (e.g., docs-assets) and referencing them in the customAssets section of your configuration. If you want to replace any of the default images or logos, this can be achieved by simply adding your own image file and naming it the same as the one you would like to replace.

Add additional modules​

You can specify additional modules to be included during documentation generation using the additionalModules configuration in your chromia.yml file. This is particularly useful for:

  • Including test modules that contain usage examples
  • Adding library modules that aren't part of the main module but should be documented
  • Ensuring comprehensive API documentation by including supporting modules

Configuration example​

docs:
  # Other configuration options...
  additionalModules:
    - test.doc_module
    - test.examples
    - lib.common_utils

Usage notes​

  • Each module should be specified with its full path (e.g., test.module_name or lib.module_name)
  • Test modules can be valuable for documentation as they often contain practical usage examples
  • You can organize your test modules specifically for documentation purposes (e.g., creating a test.doc_examples module)

Troubleshooting​

If you cannot view the navigation bar and you haven't added any custom styling that would cause this, it is most likely because you are not running the site on a web server. Two quick ways of running it on a server would be:

  1. Using Docker
docker run -dit --name my-docs-site -p 8080:80 -v "$PWD":/usr/local/apache2/htdocs/ httpd:2.4
  1. Using Node.js
npm install http-server
npx http-server

Custom styling not applied​

If your custom styles are not being applied:

  • Check that the CSS file is correctly referenced in your chromia.yml
  • Verify that the CSS selectors match the elements in the generated HTML
  • Inspect the generated HTML to understand the structure and class names