Generate documentation from source code

[yorickpeterse]

Inko's compiler should provide a way of generating documentation from source code, using the command inko doc. When doing so, dependencies of the project (i.e. everything not in ./src) should be skipped.

The output of this command is a set of JSON files, with one file per Inko module. Each JSON file contains the documentation of the module, its types, methods, etc. We won't be producing HTML directly, as I don't want to maintain what is basically a static site generator.

Inko's lexer already supports extracting comments, but the parser just discards these. We'll need to provide an option which when set causes the parser to store the comments somewhere for later use.

Generating documentation would still run the type checker, as generating documentation depends on typing information. Essentially we'd have to map the source comments to entries in the type database, then serialise that to JSON.

[yorickpeterse]

The inko-doc branch now contains the necessary changes to produce a bunch of JSON files containing documentation information. Rather than including a static site generator (amongst other things) directly in the inko executable, we'll use https://github.com/inko-lang/idoc to turn these files into HTML and what not.

For this to work, the idoc executable needs to know where the assets are stored such that it can copy them over into the generated site. The paths for that should be configurable at build time, meaning we'd need to include https://github.com/inko-lang/inko/issues/664 as well.

[yorickpeterse]

https://github.com/inko-lang/inko/issues/664 is taken care of. The next step is to upgrade the following packages to be compatible with Inko 0.15.0, such that we can use them to build the documentation generator idoc:

• [x] https://github.com/yorickpeterse/inko-wobsite
• [x] https://github.com/yorickpeterse/inko-builder
• [x] https://github.com/yorickpeterse/inko-markdown
• [x] https://github.com/yorickpeterse/inko-syntax

[yorickpeterse]

https://github.com/inko-lang/inko/commit/cefa6649c7959ee293e118bb1f2dd9e53d86781d adds the inko doc command, producing a set of JSON files containing documentation information.

https://github.com/inko-lang/idoc/ takes these files and converts them to HTML. idoc uses dependencies not part of the standard library, meaning that a new Inko release may require some changes to be made to idoc after the Inko release. If we ship idoc as part of a release, this creates a circular dependency preventing us from releasing a new Inko version. Turning idoc into a separate tool means that in the worst case we have to re-run some failing CI job to generate a release's documentation files, which won't block a release as this will be done at the end of the release pipeline.

[yorickpeterse]

For installing idoc, one can just use the make install task for the time being. In the coming weeks I want to set up something like https://docs.rs/ such that most users won't even need to install idoc to begin with.