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. docs.ada.dev).
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 readthedocs.org?
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 ada.dev… 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 search.synack.me, 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 docs.ada.dev, then a readthedocs solution is still better than no solution.
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 docs.alire.dev is good enough and gains traction, authors can start migrating docs to that platform
For me the issue here will be the lack of homogeneity. If you look at docs.rs (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.
I will report to the team.