Hey guys and gals,
I’m wondering: Is there something akin to Sphinx in Scala?
For those who don’t know it, Sphinx is the standard Python documentation library. It allows mixing code documentation with “normal” documentation (e.g., I don’t need to create a class/package/object to explain the general guidelines of the whole project).
I had a look at Scaladoc – which I’m following – but so far I didn’t find a way to do this kind of mixing.
My ultimate goal is to have a descriptive page with all documentation (business rules, design decisions, packages/traits/objects/classes documentation) in a single place, where I can define the navigation.
(And before anyone mentions it: Sadly, the scala-domain for Sphinx does not work.)
Speaking as a library consumer, please don’t. Scaladoc is uniform, fairly task-oriented (assuming your API is), and integrates into pretty much all editors. I get somewhere between annoyed and enraged every time I’m interacting with a library that decides that they’d much rather shove me into their “curated” “cookbook” instead. Yes, I’m looking at you, scalajs-bundler. †
Wanting project-wide documentation is fine, but doesn’t belong together with your API reference anyway. What language you used for the implementation doesn’t really matter here, use Sphinx, Jekyll, or whatever to your heart’s content. But always ask yourself “does this belong in Scaladoc instead?” every time you add something new.
† I have nothing (else) against scalajs-bundler or the team behind it. It has seemed to work fine in what little I’ve used it so far. It’s just an example of a library that I recently really wished had uploaded their Scaladocs.
Here is the problem: Yes, it’s project-wide, but I need to point all the moving parts.
What I have here is a Flink consumer pipeline: There is a bunch of decoding, splitting, transforming and all the jazz. Thing is, one step of the pipeline is based on the previous and, thus, I need to point out how every piece connects to the next (or the previous).
Now, I don’t want to maintain two different documentation systems. Documentation is one of the first things to go to heck and if someone needs to update to moving pieces, you’re going for disaster.
Personal opinion, after years working with Sphix, is that API reference is only useful when people have a good grasp of the API (maybe they remember there a function that returns a certain type, but not its name). For things like giving explicit explanation of how things work, a full documentation is waaaaayy more helpful.
But, again, this is my personal opinion.
This is something that Doxygen got right. It lets you add descriptive material that is not attached to any specific piece of code, but is part of the documentation, written using the same markup, and can link to classes, methods, etc. So you can generate your user guide, your tutorials, and your API reference using one tool in one pass.
The Scala documentation approach seems committed to a different style. I suspect a proposal of Scaladoc support for non-API documentation wouldn’t go far, but maybe I’m wrong. It’s not like anyone would be forced to use it.
What about package-level Scaladoc? The standard library seems to use it pretty nicely. It was a bit hidden back in 2.11, but the 2.12 redesign made it a lot more visible.
package-level doc is better than nothing, but the linked example illustrates some of the problems. The page has documentation for all the things at the package level, which is a lot of distraction for introductory readers. And the first thing it does is point to a multi-page user guide that’s not done in scaladoc. You can’t break up the package-level doc into multiple pages, so it would be a challenge to get a similar structure using scaladoc.
Yes, I’m back after this long. I finally got the time to test the suggestions and… they performed poorly.
I mean, Sphinx is not simply a “ReStructuredText to Markdown”; it can mesh your RST docs with the documention extracted directly from sources. I mean, take a look at the Django Model Field documentation; the very start is pure RST, but when you get to the fields themselves, their documention is coming directly from the Python sources.
And that’s what I’m looking for: Something where I can put together some high level explanation of how things connect to each other followed by their original document.
(If only the Scala Domain for Sphinx wasn’t broken…)
The most similar tool I am aware of for Scala is Paradox. This may be what you are looking for.
One glimpse at all the possible options is to look at the integrations with
PS: Personally, I like Paradox.
Well, not quite. I mean, for all it looks, it seems SbtSite is simply a way to run two generators at the same time (or one after the other). There is no way where I can write my Markdown/RST and include the documentation from the source.
For example, in Sphinx, I could write something like this:
To make this work, your classes must implement this interface:
… autoclass: base.interfaces.BaseClass
The generated output is not a link to
BaseClass or anything like that; it’s the documentation of
BaseClass. If I change the documentation of it – because I changed the code to add another field in the interface, for example – Sphinx will pick it up and update the documentation (the sames goes for modules, classes and whatever).
This is really good because a) My code can be kept up to date with the current implementation and b) If I change the code documentation, I don’t need to hunt down whatever I added that reference.
Not only that, but because I can select what I want to auto-doc, I can either select the order or even keep internal things documented in their code, but without being extracted to the project docs.
I’m not saying the current scala doc tools are terrible but… the current scala doc tools are terrible.
@juliobiason - also need to “point all the moving parts.”. Have done a lot of investigation and can see a lot of pieces but nothing to tie them all together.
Please see 4-5 tweets from me here
https://twitter.com/semanticbeeng/status/1079445197484904450 and thoughts here https://github.com/vsch/idea-multimarkdown/issues/created_by/SemanticBeeng.
This is not about Scala only so not sure this place is best to discuss.
If you review above and like to take it further then please let me know.