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.

idoc TODO

• Add README
• Set up release tools
• Publish a Docker container
• Figure out how we'd instruct users to install idoc
  • Related: Make it easy to install Inko applications #663

Inko TODO

• Generate standard library documentation after publishing the release archive
• Generate standard library documentation for main for every push
  • How do we deal with cases where main introduces breaking changes, but the third-party dependencies target the latest public release? Do we just allow this job to fail?
• Should idoc be a separate repository, or be included in the main repository?
  • If idoc is a completely separate tool (that just happens to ingest data from inko doc), then keeping it separate is probably best
• Document the new setup

[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 #664 as well.

[yorickpeterse]

#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:

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

[yorickpeterse]

cefa664 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.