The new GNATdoc is available, let's create a `` website (mabye?)

Using Alire 1.2.1 if you update your index (alr index --update-all) you will have access to the new gnatdoc implementation based on Libadalang.

This is the opportunity for me to start on project I have in mind since a long time, a website that provides a collection of documentation from all the Alire crates (a.k.a.

I would like to gather feedback here, what this website should look like and do in your opinion?
Or even, is it a good idea to make such website as opposed to push documentation to existing platforms like


I like the idea of having autogenerated gnatdoc all in once place. I don’t have a strong opinion on whether it should be on readthedocs or… Whatever’s easiest to maintain and automate updates.

If we’re going to maintain docs for all versions, not just the most recent one, the storage requirements will be significant. With, I’ve been storing snapshots of every crate in the index. The most recent snapshot is 7.9GB without counting the size of the search index. I’m planning to migrate to a content addressing approach and store the sources on S3, to reduce the cost of storing multiple versions of the index.

Somewhat unrelated, I had some trouble getting the new gnatdoc to build with Alire… It seems to call the gprbuild binary from my system PATH rather than using the Alire-installed one. I had to remove my system installed gprbuild and gnat entirely to get it to use the Alire toolchain. Doing this in a clean debian:bullseye Docker container, I found that it’s missing a build dependency on libc-dev for limits.h.

I used the gnatdoc binary bundled with Gnat Studio a little while ago. I was pleasantly surprised that it seemed to work offline with some js even and without a server.

Go used to bundle Godoc with the Go release. Now you have to build it, but it makes offline documentation easy. It would have stdlib docs by default and then docs for whatever crates were in the working directory. I believe you could also specify project folders by command line upon execution (it would start a go web server).

It looks like gnatdoc could do the same but without the need for a server?

I assume the same code was used to generate the Go docs that they had online too as they looked the same.

I like the idea of having some sort of searchable docs. I guess it would depend on the time/cost tradeoff. Ideally, I wouldn’t use readthedocs as it isn’t super user friendly. You have to know what you are looking for to find stuff there. But if it is too costly to make something like, then a readthedocs solution is still better than no solution.

1 Like

In my opinion, it would be better to open the possibility to upload the whole documentation, a reference (URL, repository) or just a single file (markdown, html, pdf, text). Authors will choose which one is better to their crate. For some authors, documentation will perfectly fit in readthedocs. For others, with just a README file is enough.

With this you’ll have:
1. a central place of docs, references or files
2. a quick way to start gathering documentation (no migration / rewriting needed)
3. if the interface of is good enough and gains traction, authors can start migrating docs to that platform

So I think the idea is to generate docs from annotated comments. Hopefully people will add examples using the code annotation.


For me the issue here will be the lack of homogeneity. If you look at (e.g. here), whatever the project you are looking at, everything looks familiar and homogeneous.

I also want something that is as automated as possible, you don’t have to do anything to have at least a basic API doc available.


It would be nice to have some instructions on how folks are supposed to use this. I tried using it after building it from Alire and using it on Windows last night and it didn’t seem to do or output anything. The older versions seemed to get hung up on trying to deal with subprojects. It’d be great if there was a alr doc command to do this for you.

Sure! I prefer completeness and a central place over homogeneity. If automation can bring basic documentation for APIs, that’s perfectly fine and desirable. But IMMO other levels of documentation could co-exist as well. For example for requirements, architecture and design (UML diagrams), testing, proofs, etc…
You want something as automated as possible, I’m thinking in something as open as possible. Combination of both ideas could be great!

It would be nice if alire selected the project file for you I guess.

Perhaps it is a Windows variant issue? The binary from Gnat Studio gives you the commands with --help. Have you tried /?

On Linux you just give it a project file if I recall correctly with -P. There is an output format which doesn’t seem to be explained in --help but it is explained online.

alr doc is definitely something we can consider.

In the meantime, with gnatdoc4 in path, you can generate documentation like so:

$ alr exec -P -- gnatdoc4

The output will be in a gnatdoc folder inside the object directory.

I made a first, very basic, proof-of-concept here:

  • List of crates
  • List of releases of a crate
  • Documentation for the release of a crate
1 Like

Should it work for a project where old gnatdoc worked? For example, from GitHub - mgrojo/ASFML: Ada binding to the SFML library

alr exec -P -- gnatdoc4 does nothing.

Directly running gnatdoc4 -P asfml.gpr

raised LANGKIT_SUPPORT.ERRORS.PROPERTY_ERROR : dereferencing a null access

Is this a bug?

Edit: I just saw which has the same exception.

The new gnatdoc is a complete rewrite based on LibAdaLang, so don’t expect backwards compatibility.

Any explicit raise is almost certainly a bug :slight_smile: I will report to the team.

this I do support, sounds like JavaDoc and should not be a problem to get it into the community

New version:

(Links work now)

Sorry, most of the links are broken. (“it works on my machine”)