Documentable vs Collection

[2colours]

Hello,

hopefully we can have the new docs site set up really soon, and I found a ticket regarding the use of Collection - the way I read it at least - as opposed to Documentable.

To be honest, I know very little about Documentable itself, I'm mostly asking people who know more about it and/or know about Collection. @Altai-man @finanalyst please feel addressed. :)

• how does Documentable relate to each other?
• if they are providing a solution for the same problem: is there an intention to switch Documentable to Collection? What are the possible benefits and drawbacks?

Thank you in advance.

[JJ]

I don't know about Collection, although I'm pretty sure @finanalyst has made a pretty good job and it's a strong system for generating static sites.
However, compatibility of Documentable with the current state of the document source needs to be evaluated. Since static generation of the documentation has been discarded, I don't think it's really worth the trouble. So, answering your questions to the best of my knowledge

1. Collection is in the same broad category as Documentable: static generation of the content from source. As far as I can tell, Collection works while Documentable, currently, does not. (I can't tell if it does with the current state of the source, though).
2. I can't comment about any kind of intentions here. FWIW, I would endorse Collection over Documentable any time.

[Altai-man]

how does Documentable relate to each other?

Documentable and Collection? From my point of view:

Collection is a tool like Doxygen for Raku, on steroids and with comics superpowers. It takes Pod documents and does a highly configurable with plugins and middleware process of converting this Pod to a set of documents in some other format (be it HTML or something else if configured so).

Documentable is a library and a tool in one package. The library gives you API to obtain structured Pod out of a collection of files. You can initialize with a directory of pod files and then ask "Ok, give me all documents marked as types" or "Ok, give me pod of this subroutine" or "Give me pod document of this type, but with methods of ancestors included". Then you can use this API to render the pages and serve them or write them on the disk.

And the tool I mentioned does the "writes them on the disk" part: it's a rather hardcoded algorithm of how to convert a set of pod files in doc into a static website.

As from my website perspective, because I base it around API the Documentable gives, I don't really care who is the provider, if Collection can provide the same runtime API (rather than just generating files), I can use it too.

if they are providing a solution for the same problem: is there an intention to switch Documentable to Collection? What are the possible benefits and drawbacks?

This is where the sad parts begin. As I wrote, they do two different things, so Collection cannot be a drop-in replacement for Documentable as it is now. We have a ticket opened for @finanalyst to work on (Altai-man/docs.raku.org#67) what API should be provided for it to be compatible, but he has plenty of $life things going on I believe and so it is not actively worked on.

[finanalyst]

Hi. I am working on Collection quite actively. But I also have a day job.
There is a stack of Modules for rendering Raku documentation. There are several hundred files. I am trying to write software to manage the whole stack, and to provide the extra functionality we need for the future.

The stack at present is:
Pod::From::Cache -> Documentable -> Pod::To::HTML

The Collection stack is
Pod::From::Cache -> Collection -> ProcessedPod

ProcessedPod uses templates that can be changed without changing the software.
Pod::To::HTML hard codes all the HTML rendering.
Pod::To::HTML does not allow for new Pod::Blocks or Formatting codes. But we need a way to include new information into the Raku documentation to account for changes in the language - some things are deprecated, some are new. One way to do this would be to have a new formating code to indicate deprecations, and for the renderer to show this or not show these changes.

In addition, we should be able to have translations of the Documentation and to make it easy to synchronise the translations. This is not possible using Documentable.

Documentable is heavily dependent on Pod::To::HTML.

I am trying to show how Altai-man's work can be based on Collection, but only I am doing the work. So it is slow.