Generate structured documentation

New to Julia
,
1

I’m new to Julia and try to use different packages.I find it hard to use the documentation (when it exists). I appreachiate all descriptions and examples and everything in the docs, but I miss pages like “Here is type X and here are all the methods that take a parameter of this type. Also, X is a subtype of Y and is supertype of A and B.”

Example: In Meshes.jl there exist a type SimpleMesh which is a subtype of Mesh. This information is not very prominent on the page (yes it is in the description at the top, but it is not mentioned in the boxes for the types themselves.) Also stuff like "You can call the method vertices with a Mesh as parameter is missing

  1. I didn’t find something like this. Is it not something that most people woud like to use? Do I “program the wrong way”?
  2. Is there a package that generates such overviews?
2

Well, documentation is written by humans and for humans, and writing documentation is hard and time-consuming. There’s tooling, but it’s not perfect.

First, I think everyone should often and repeatedly internalize Daniele Procida’s system for writing good documnation (the “Divio” system as it’s now called). I agree with you that with systems like Sphinx for Python and Documenter for Julia which emphasize generating documentation from human-written markup documents, too many people somewhat neglect good and complete API documentation (the “Reference” category of the system), which has to closely mirror the code and thus usually should be auto-generated.

Documenter.jl has @docs and @autodocs which helps with generating API docs. But, you have to write good docstrings first (including information like subtypes/supertypes/supported methods, etc.). Also, @autodocs has some problems: it gives you a wall of text, with very little structure. I’ve found that the best way to generate API documentation is to write a custom script like this one: QuantumControl.jl/generate_api.jl at master · JuliaQuantumControl/QuantumControl.jl · GitHub which produces this: QuantumControl · QuantumControl.jl

I’m not sure how easy that would be generalized into improvements for Documenter.jl. I’m sure
@docs/@autodocs could be improved, or additional syntax (like this one) could be introduced.
To some extent, Julia’s flexibility works against automatic API documentation, compared to, e.g., Java, where javadoc can generate very complete information, due to Java’s very strict object-oriented philosophy. Julia is much more messy, and thus requires more human judgement when writing API documentation.

In any case, there’s nothing wrong with your desire for good API documentation. Realistically, though, the only thing to do is to put in the effort for the documentation of your own packages, and maybe contribute to the documentation of existing packages where you can.

6 Likes
3

Divio: I am all for it. I tried to organize the docs on these principles here:
https://petrkryslucsd.github.io/FinEtools.jl/dev/
As you say, @autodocs is a blunt instrument.

1 Like
4

Literate.jl is also a good tool for integrating examples as notebooks in the docs

1 Like
5

This is possible to do, but would require different tooling than is currently in widespread use by the community. For example, https://fluxml.ai/FastAI.jl uses https://lorenzoh.github.io/Pollen.jl, which handles API reference documentation a good bit better than the status quo. The bigger problem IMO is that there are only X number of dev hours these days to work on documentation, and most of those are necessarily put towards maintaining systems like Documentor instead of experimenting with/developing new ideas.

One wonders if this would be a good place to attract new contributions, as working on a docs system doesn’t require any specialist knowledge in particular scientific/numeric domains. That said, I do agree that the relative scarcity of static type information in a lot of Julia code makes something around the level of JavaDoc/RustDoc difficult.

2 Likes
6

One of my current long-term goals with Documenter maintenance is to make it more plugin-friendly, so that it would be possible to experiment with ideas within Documenter, and not having to re-invent a whole new package to try out one idea. But this itself is a pretty large maintenance / refactoring task.

The Pollen-like autogenerated reference pages for objects (e.g. stuff like full method lists etc) is something that I have always wanted to experiment with in Documenter (it was actually in my first GSoC proposal). I just haven’t found the time to play with the idea yet. It would be a great project for a Documenter plugin though if anyone wants to tackle it (and maybe could also share some code with Pollen here).

6 Likes
7

Thank you for all your answers! I’ll have a look at the different provided links. And if I develop a package I’ll try my best to provide good documentation :slight_smile:
Thanks for pointing out why documentation like this is rare (limited time obviously, but also different handling of types in Julia)