Generate documention with mutiple versions

Learning Resources
1

Hi everyone,

Today I would like to share to you a tutorial I made to know how to generate a documentation for your project in Crystal.

I will show you an example with my own project ISM (this tutorial was realized on Gentoo Linux).

So first go inside the directory of your main project.
CrystalDoc1

Open a terminal at this location.

CrystalDoc2
CrystalDoc2984×652 22.1 KB

Now type in the terminal:

crystal docs --json-config-url=versions.json

If your project don’t use shard, like my project, you will need to specify more options, the project name, and the main file of your project.

CrystalDoc3
CrystalDoc31815×687 69.3 KB

The option –json-config-url set which file will control the redirection to the other version pages. You can set the name you wish for this file. This file will inform the website when the user will be on the current page where the website we will need to come back if the user will request to see an another version.

This file look like that for me actually. Just adapt it for your project:

{
  "versions": [
    {"name": "Alpha-06012023", "url": "/api/Alpha-06012023"},
    {"name": "Alpha-13022023", "url": "/api/Alpha-13022023"},
    {"name": "Alpha-14032023", "url": "/api/Alpha-14032023"},
    {"name": "Alpha-07072023", "url": "/api/Alpha-07072023"}
  ]
}

You need to make this file for each versions you will generate, or the user will not be able to come back to the main page of your documentation.

So of course, you need to adapt this file for each version to make sure the user will be able to come back to the main page (master in my case).

Actually we generate the main page, because by default my project is on master branch. Everything was generate in the ./docs directory.

Now clone your repository somewhere else and repeat the same action for each version you need to generate a documentation.

When it’s done, in your main project directory on master, in ./docs, make a directory for each branch you generated the documentation before. And copy inside each directory the content of related generated documentation.

As I said previously, don’t forget to make a versions.json file for each directory.

Normally your directory will look like that:

CrystalDoc4
CrystalDoc4553×711 38.3 KB

Now just copy all of that in your server, and it’s done !

6 Likes
2

While working on crystaldoc.info, I ran into this too. Thank you for the tutorial! The versions.json can be anywhere on the server/docs, and the json-config-url option just sets the path the browser should get the versions.json from. If you put it at the root of your docs, you can do --json-config-url=/versions.json and everything should work.

2 Likes