Running the repo with docs‐builder

Guidelines on running this repo with docs-builder

Docs Builder is a Gatsby-based platform for building documentation websites for Telerik and Progress DevTools products.

Prerequisites

In this tutorial, we will be using the reporting, report-server-docs, and docs-builder repos. It is recommended that you clone them in the same directory locally, so that you can easily follow the tutorial without needing to adjust the paths.

The folder structure should look like:

.
├── reporting/
├── report-server-docs/
└── docs-builder/

After cloning the repositories, open a new terminal in the docs-builder report and run the command npm ci to install the required node modules.

Getting Started

1. Open the report-server-docs repo in a text editor of choice. The recommended one is VS Code.
2. Open a new terminal and run the commands:
   • cd ..
   • cd docs-builder
3. Run the command npm run develop --docsPath=../report-server-docs.
4. Navigate to http://localhost:8000/ to open the locally built docs site.

This will start the docs site in development mode, and any changes you make to the MD files will be reflected immediately.

The site will be without API Reference, so you may see errors in the output for non-working links on pages where there are /api/ links.

Generally, if the content is properly formatted in development mode, it will look the same in the production build. However, if there are, let's say, incorrect slugs, those will be noted when you try a production build. The API Reference is needed for that.

Production Build

Triggering the production build in docs-builder

Unlike with the reporting-docs repo, this repo can be fully built without the REST API MDs and the API Ref.

1. Go back, in the terminal, to the docs-builder directory.
2. Now run the command - npm run build --docsPath=../report-server-docs
3. When the build finishes, run the command npm run serve to display the site on http://localhost:9000/report-server/documentation/introduction.

Generating metadata for API Ref

1. First, make sure that you have installed docfx on the computer. If you have not, it can be installed with the command:

   • dotnet tool update -g docfx

2. We need the following assemblies to generate metadata:

   • Telerik.ReportServer.Services.Models.dll
   • Telerik.ReportServer.HttpClient.dll

   Copy them into -> report-server-docs/_assetsApi/Bin

3. In a terminal, navigate to the reporting-docs/_assetsApi directory. If you have opened the reporting-docs repo as suggested earlier, you can use:

   • cd _assetsApi

4. Now, again in the terminal, run the command docfx metadata, which will generate a metadata folder with the yml files.

The final structure of the report-server-docs/_assetsApi folder should look something like:

_assetsApi/
├── Bin/
├── metadata/
├── docfx.json
└── filterConfig.yml

6. Now, navigate back to the docs-builder folder, and run the following command to build with the API Ref:

   • npm run build --docsPath=../report-server-docs --docFxFilesPath=../report-server-docs/_assetsApi/metadata

Fixing/Avoiding Production Build Errors

The most common errors causing the build to fail are about incorrect slugs. If there are many wrong slugs, not all of them may be visible in the first build, so you may need to fix -> rebuild a couple of times.

Use double curly braces only for liquid syntax(those are the version variables we use, such as the Blazor UI version). If you need to use double curly braces somewhere in the text, escape them:

\{\{ text \}\}

Use relative paths when referencing images to avoid errors related to the image not being found(the URLs are different after build).