What is the recommended way of including proper no...

# dokka

[CLOVIS]

What is the recommended way of including proper non-code documentation pages in the Dokka output? As in, not just the module/package headers, but proper full-blown pages for tutorials, that have the possibility to link to code etc, like all Dokka code can do.

I'm half-tempted to create a documentation module that just contains object s with documentation 😅

[Javier]

The general rule I have seen on open source projects is using Dokka mainly for API docs and using mkdocs, docusaurus, etc for the website.

[CLOVIS]

That makes sense, but it's so much more convenient to have everything in a single tech with easy cross-referencing :/

[jaguililla]

Hello, you could use the Jekyll Dokka plugin to use a single tool to generate your documentation.

As far as I know, the only two options out of the box are: GFM to GitHub and Jekyll to GitHub Pages.

Me myself, I generate the API documentation to GFM, tweak the files a little bit, and add that to the rest of documentation to be rendered with MkDocs.

Good luck!

[hfhbd]

What about just including md files?

[CLOVIS]

@hfhbd that would be ideal, but from what I could see you can only include a short description for a module/package, right? Not an entire page

[hfhbd]

Oh yeah, you are right. I checked our internal documentation and we only use this format https://kotlinlang.org/docs/kotlin-doc.html#module-and-package-documentation resulting in a big merged page split only by the headlines.

[Ignat Beresnev]

As has been pointed out, Dokka is used primarily for API reference documentation. Embedding a full blown non-code documentation engine would take precious time and add to the maintenance burden quite a bit 🙂

If you really want to combine the two, you can write a Dokka plugin that can generate additional HTML pages alongside code documentation. This way you'll be able to read whatever files are available to the plugin, process them using whatever engine/markup language you want, and generate desired output. It won't be easy, but it's doable.

If you decide to follow this path, I can give you some pointers as to where to start

People have asked about this a few times already, so it could be good community plugin

[CLOVIS]

Well, the thing is, I would be very happy with exactly the same thing as we have for the module/package header file, but that generates a different page in the final output

That file already has cross-referencing with the rest of the documentation, proper code highlighting...

[Ignat Beresnev]

Alternatively, OkHttp is embedding Dokka-generated Markdown documentation into their MkDocs documentation, example here

But Markdown format is still in Alpha, so it's not as pretty and there are some noticeable bugs

[CLOVIS]

Sorry, I meant the markdown input, not output.

Currently, I can include a file that looks like this;

# Module whatever

This is the description of the class [Foo][com.whatever.Foo].

and Dokka will correctly render the contents, with highlighting, linking etc to the other pages.

I'd just like to be able to use this syntax to create a new file that is rendered exactly the same way, just as its own page instead of as the description of the module.

[CLOVIS]

I completely understand that you don't want to go the route of making Dokka a full-blown generalist documentation generator, but for my use cases all the current features in a separate page to avoid cluttering the main one would be enough

[CLOVIS]

How hard do you think this would be? My understanding is that it only changes the generated file architecture (I guess changes need to be made to the indexing so they can be found), but no changes to the actual HTML/formatting is necessary

[Ignat Beresnev]

Yeah, you'd still have to modify Dokka (or write a plugin) in order to do that 😞

Module and package descriptions are part of the KDoc spec, similar to Java's package-info.java file, that's why it's supported, but it doesn't go beyond that

You could certainly re-use Dokka's Markdown parser and the rest of functionality, this would then be easier.

However, I've had a look at how you can implement it - looks like it's not possible at the moment as Dokka lacks an extension point for it 😞 I've created an issue here with some details. It seems simple enough to implement from our side, so I'll try to address it in the near future, will keep you posted.

[CLOVIS]

@Ignat Beresnev do you want me to try to redact a proper summary in an issue?

[Ignat Beresnev]

@Ignat Beresnev do you want me to try to redact a proper summary in an issue?

Probably not, but you can describe your use case in the comments of the issue so that it doesn't get lost.

Once the extension point is implemented, we'll have to write tests anyway, so there you'll see an example of how to use it