How to generate documentation for Crystal's compiler?

Help & Support
1

Are there any recommendations?

2

What kind of documentation are you thinking of? Like manually building the API docs you can see at Crystal 1.11.0-dev or?

1 Like
3

Yes.

4

There’s a make target for it:

make docs
5

I just tried it. But it doesn’t generate documentation for the classes that make up the compiler.
Is there an option to generate documentation for the compiler?

6

No, the compiler docs are considered internal/private so there are no public API docs for them. There still may be comments on things, but there isn’t a rendered view of them.

Compiler internals · crystal-lang/crystal Wiki · GitHub may be worth a read as well, but not sure how up to date it is.

1 Like
7

I looked at the Makefile. It runs docs_main.cr.

.PHONY: docs
docs: ## Generate standard library documentation
        $(call check_llvm_config)
        ./bin/crystal docs src/docs_main.cr $(DOCS_OPTIONS) --project-name=Crystal --project-version=$(CRYSTAL_VERSION) --source-refname=$(CRYSTAL_CONFIG_BUILD_COMMIT)

I edited docs_main.cr and it generated the documentation for Crystal’s compiler.

diff --git a/src/docs_main.cr b/src/docs_main.cr
index 661163677..1f7cbb04b 100644
--- a/src/docs_main.cr
+++ b/src/docs_main.cr
@@ -5,6 +5,7 @@
 require "./annotations"
 require "./big"
 require "./compiler/crystal/macros"
+require "./compiler/requires.cr"
 require "./compress/**"
 require "./crypto/**"
 require "./crystal/syntax_highlighter/*"

I guess that’s the solution for now.

8

You can add the compiler entry point to the docs command via Makefile argument:

make docs DOCS_OPTIONS=src/compiler/crystal.cr

This generates the combined API docs for the compiler and stdlib.

3 Likes