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

waleedmebane · March 4, 2026, 6:44pm

That sounds like a good approach. Why not XML, though? It could be rendered in clients without Javascript (using XML stylesheets).

mgrojo · March 4, 2026, 7:39pm

Is this due to a missing external dependency, or where is the problem?

asfml 2.6.1

Failed 2026-03-03

Stage:

fetch

Message:

alr get exited with code 1

Fabien.C · March 9, 2026, 10:28am

I didn’t think about this. I’m not sure if that would be a better solution though.

Fabien.C · March 9, 2026, 10:29am

You can try to run gnatdoc 26 on the crate to see is there is an error message.
This POC needs a lot of improvements, including better reporting of errors…

Heziode · March 9, 2026, 8:04pm

I am torn about that subject.

On one hand, I found the idea, like docs.rs a great thing, to centralize documentation, but on the other hand, I found docs.rs messy and very difficult to read and searching for information about a lib (as a disclaimer, I am not a pro-Rust; I am learning it to have my opinion about it).

On the other hand, I found that having all the documentation in the code is neither desirable nor possible (how do you make a graph inside a code to explain something?, if you use Mermaid, it renders well in a browser / external document but it is difficult to read in the code; if you make an ASCII graph, you have the opposite).

I had this thought a year ago (Markdown output format · Issue #32 · AdaCore/gnatdoc · GitHub) but my conclusion is summarized with what I said in the last paragraph: you can’t put all your documentation in your code. This is in line with The new GNATdoc is available, let's create a `docs.ada.dev` website (mabye?) - #9 by rocher

I would see something more like Nuxt where you have the doc in markdown (by following a documentation “framework” like Diátaxis, and with an “augmented” markdown with custom HTML tags, e.g. MDC), and auto-generate the API part of the doc with gnatdoc.

EDIT: I have not saw that is an update of an old thread

A new gnatdoc backend generates a JSON representation of the documentation. Then the static website will serve a page with JavaScript code that renders the documentation on the client using the JSON files.

@Fabien.C this is mostly the way followed by modern web frontend frameworks, like React/Next, Vue/Nuxt, etc. So what you did doesn’t seem crazy.

BTW, is it normal that it only render package compilation unit, and not sub-program (procedure/function) compilation unit?
For example: distance — Ada/SPARK Documentation

Only show:

But not distance/src/distance-numeric-euclidean_generic.ads at e265e32656db1284ef750cbd473db95424e5b215 · adarium-labs/distance · GitHub as an example

Fabien.C · March 11, 2026, 9:04am

@Heziode I share some of you concerns. API doc is not enough, but it’s a good start.

One of the main goal for automatically generating the doc without any action on the developer side, is to “encourage” developers to care about the API doc.
And encourage them to use a format that will play nice with the ecosystem, like vscode plug-in for instance. I don’t think the website would be the main way to consume this info (far from it).

Not normal, but this is a proof-of-concept
It looks like GNATdoc is not generating a JSON for this unit: docs.ada.dev/data/distance/0.1.0 at gh-pages · alire-project/docs.ada.dev · GitHub

Could be an issue with the JSON backend…

Heziode · March 12, 2026, 5:55pm

I see, which is also important in Ada, since we reads .ads

Yes, if the target is to be consumed by an LSP (ALS) to be displayed inside a code editor/IDE, I said a big YES, this is the thing I want (that partly works for me on VS Code, but, I will open an issue later, when I am sure how to reproduce it).

I have not tried to tell GNATdoc to generate an HTML doc for this project; maybe there is an error on a specific output

krischik · March 28, 2026, 3:48pm

Sounds fine. I already publish gnatdoc with all my crates which I found very helpful. Especially with the Raspberry Pi Pico crates. Documentation is lacking everywhere.

Sometimes when I type a search term into Google for some Ada library I directed to my own gnatdoc because the original author never bothered publishing gnatdoc alongside his project. A central side might improve that.

And here we have the main problem. Alire have a package manager and an package manager should just install gnatdoc4 when needed. Having to install gnatdoc4 is a annoyance. And because of updates not a one off annoyance.

Pretty cool. However long_description is markdown and has new lines. Just making it a wall of text doesn’t do longer descriptions justice.

Fabien.C · March 30, 2026, 12:08pm

We are working on binary releases of GNATdoc to use in CICD.

One of the many problems with this proof-of-concept

kevlar700 · April 14, 2026, 1:30pm

I’m impressed that it can output an odf (.fodt) . Also cool that it comes with Gnat Studio with quarterly updates now it seems which helps encourage it’s use.

kevlar700 · April 14, 2026, 1:53pm

I believe I would want to use --style leading. I actually forget why exactly right now but it has something to do with it working more consistently across tools like svd2ada and hovering in gnat studio etc. for me. Is there a way to store that preference in a crate?

kevlar700 · April 14, 2026, 2:43pm

I’m having trouble getting a code example to display.

Is Text Markup a work in progress or is there a model crate to look at such as the gnatdoc crate?

godunko · April 14, 2026, 3:10pm

GNATdoc supports Markdown dialects, for code blocks try to use ``` format

```
X : Integer;
```

or “three spaces deeper” format

This is declaration of `X`

   X : Integer;

kevlar700 · April 14, 2026, 3:12pm

Neither seems to be working. The three deep definitely used to work

Maybe I’ll try gnatdoc from alr

kevlar700 · April 14, 2026, 3:20pm

I’m trying to get the following to display as shown. Three leading spaces puts it on one line and backticks make it look monospace but all on two lines.

   Z85_Alphabet : constant BToA.Alphabet_85 :=
     "0123456789" &
     "abcdefghij" &
     "klmnopqrst" &
     "uvwxyzABCD" &
     "EFGHIJKLMN" &
     "OPQRSTUVWX" &
     "YZ.-:+=^!/" &
     "*?&<>()[]{" &
     "}@%$#";

Lucretia · April 14, 2026, 6:32pm

I tried to alr with gnatdoc to this sdl3ada repo to try to see what it generated, but it fails to build with 15 and 16.

$ alr run gnatdoc
warn: The following external dependencies are unavailable within Alire:
warn:    libgmp*
warn: They should be made available in the environment by the user.
warn: Generating possibly incomplete configuration because of missing dependencies
◷ Syncing build dir... warn: Generating possibly incomplete environment because of missing dependencies
ⓘ Building gnatdoc=24.0.0/gnat/gnatdoc.gpr...                                  
Compile
   [Ada]          gnatdoc-driver.adb
   [Ada]          vss-xml-templates-processors.adb
   [Ada]          vss-xml-implementation-template_programs.ads
   [Ada]          vss-xml-implementation-template_parsers.adb
   [Ada]          vss-xml-implementation-template_namespaces.adb
   [Ada]          vss-xml-implementation-template_evaluators.adb
   [Ada]          markdown-simple_inline_parsers.adb
   [Ada]          markdown-parsers.adb
   [Ada]          markdown-parsers-gnatdoc_enable.adb
   [Ada]          markdown-list_items.adb
   [Ada]          markdown-list_items-internals.adb
   [Ada]          markdown-inline_parsers.adb
   [Ada]          markdown-implementation.adb
   [Ada]          markdown-implementation-thematic_breaks.adb
   [Ada]          markdown-implementation-quotes.adb
   [Ada]          markdown-implementation-paragraphs.adb
   [Ada]          markdown-implementation-lists.adb
   [Ada]          markdown-implementation-list_items.adb
   [Ada]          markdown-implementation-indented_code_blocks.adb
   [Ada]          markdown-implementation-indented_code_blocks-gnatdoc.adb
   [Ada]          markdown-implementation-fenced_code_blocks.adb
   [Ada]          markdown-implementation-documents.adb
   [Ada]          markdown-implementation-code_spans.adb
   [Ada]          markdown-implementation-auto_links.adb
   [Ada]          markdown-implementation-atx_headings.adb
   [Ada]          markdown-emphasis_delimiters.adb
   [Ada]          markdown-documents.adb
   [Ada]          markdown-documents-internals.adb
   [Ada]          markdown-blocks.adb
   [Ada]          markdown-blocks-thematic_breaks.adb
   [Ada]          markdown-blocks-quotes.adb
   [Ada]          markdown-blocks-paragraphs.adb
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-xml-implementation-template_evaluators.adb:225:32: warning: condition is always True [-gnatwc]
vss-xml-implementation-template_evaluators.adb:225:32: warning: (see test at line 219) [-gnatwc]
vss-xml-implementation-template_evaluators.adb:596:27: error: missing "with Ada.Finalization;"
vss-xml-implementation-template_evaluators.adb:616:20: error: missing "with Ada.Finalization;"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
gpr2-project-attribute_cache.ads:89:27: error: missing "with Ada.Finalization;"
gpr2-project-attribute_cache.ads:93:15: error: subprogram "Initialize" is not overriding
gpr2-project-attribute_cache.ads:94:15: error: subprogram "Finalize" is not overriding
gpr2-project-attribute_cache.ads:95:15: error: subprogram "Adjust" is not overriding

   compilation of gnatdoc-driver.adb failed
   compilation of markdown-blocks-paragraphs.adb failed
   compilation of markdown-blocks-quotes.adb failed
   compilation of markdown-blocks-thematic_breaks.adb failed
   compilation of markdown-blocks.adb failed
   compilation of markdown-documents-internals.adb failed
   compilation of markdown-documents.adb failed
   compilation of markdown-emphasis_delimiters.adb failed
   compilation of markdown-implementation-atx_headings.adb failed
   compilation of markdown-implementation-auto_links.adb failed
   compilation of markdown-implementation-code_spans.adb failed
   compilation of markdown-implementation-documents.adb failed
   compilation of markdown-implementation-fenced_code_blocks.adb failed
   compilation of markdown-implementation-indented_code_blocks-gnatdoc.adb failed
   compilation of markdown-implementation-indented_code_blocks.adb failed
   compilation of markdown-implementation-list_items.adb failed
   compilation of markdown-implementation-lists.adb failed
   compilation of markdown-implementation-paragraphs.adb failed
   compilation of markdown-implementation-quotes.adb failed
   compilation of markdown-implementation-thematic_breaks.adb failed
   compilation of markdown-implementation.adb failed
   compilation of markdown-inline_parsers.adb failed
   compilation of markdown-list_items-internals.adb failed
   compilation of markdown-list_items.adb failed
   compilation of markdown-parsers-gnatdoc_enable.adb failed
   compilation of markdown-parsers.adb failed
   compilation of markdown-simple_inline_parsers.adb failed
   compilation of vss-xml-implementation-template_evaluators.adb failed
   compilation of vss-xml-implementation-template_namespaces.adb failed
   compilation of vss-xml-implementation-template_parsers.adb failed
   compilation of vss-xml-implementation-template_programs.ads failed
   compilation of vss-xml-templates-processors.adb failed

gprbuild: *** compilation phase failed
error: Command ["gprbuild", "-s", "-j0", "-p", "-P", "/home/laguest/.local/share/alire/builds/gnatdoc_24.0.0_8cc57c73/73969f4c7194be0c20074b552b2968a5f9d5e97c35c72a8289d4675afbb8806f/gnat/gnatdoc.gpr"] exited with code 4
error: Build failed

godunko · April 14, 2026, 7:22pm

You should use GCC14 to build this version of GNATdoc.

Lucretia · April 14, 2026, 7:44pm

Tried that, still errors.

   [Ada]          markdown-simple_inline_parsers.adb
   [Ada]          markdown-parsers.adb
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-xml-implementation-template_evaluators.adb:225:32: warning: condition is always True [-gnatwc]
vss-xml-implementation-template_evaluators.adb:225:32: warning: (see test at line 219) [-gnatwc]
vss-xml-implementation-template_evaluators.adb:596:27: error: missing "with Ada.Finalization;"
vss-xml-implementation-template_evaluators.adb:616:20: error: missing "with Ada.Finalization;"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
vss-string_vectors.ads:28:45: error: improper aggregate operation for "Virtual_String_Vector"
gpr2-project-attribute_cache.ads:89:27: error: missing "with Ada.Finalization;"
gpr2-project-attribute_cache.ads:93:15: error: subprogram "Initialize" is not overriding
gpr2-project-attribute_cache.ads:94:15: error: subprogram "Finalize" is not overriding
gpr2-project-attribute_cache.ads:95:15: error: subprogram "Adjust" is not overriding

gnatdoc is a tool, it should be provided as a binary. Or it should be capable of specifying the compiler it needs to build itself apart from the toolchain selected to build whatever I’m building.

godunko · April 14, 2026, 7:58pm

It is strange, which version of VSS it selects?

Lucretia · April 14, 2026, 8:46pm

$ alr with  gnatdoc
Requested changes:                                                                                                  

   ✓ gnatdoc ^24.0.0 (add)
                                                                                
Changes to dependency solution:

   New solution is incomplete.
   +        adasat          24.0.0 (new,indirect)
   +📦      gnat            16.0.0 (new,gnat_external,indirect,executable in path)
   +        gnatcoll        24.0.0 (new,indirect)
   +        gnatcoll_gmp    24.0.0 (new,indirect)
   +        gnatcoll_iconv  24.0.0 (new,indirect)
   +        gnatdoc         24.0.0 (new)
   +        langkit_support 24.0.0 (new,indirect)
   +        libadalang      24.0.0 (new,indirect)
   +        libgpr          24.0.0 (new,indirect)
   +        libgpr2         24.0.0 (new,indirect)
   +        markdown        24.0.0 (new,indirect)
   +        vss             24.0.0 (new,indirect)
   +        xmlada          24.0.0 (new,indirect)
   Missing:
   +❗      libgmp          *      (new,indirect,missing)

That was using gnat 16, I changed to gnat 14.x after.