Crystal: Multi folders crystal doc generation support

[rmarronnier]

Right now crystal doc generate a documentation website according to the content of a single folder, even if those different folders might have related code.

Example and real use case :

Cadmium was split recently into several shards. Yet, each of these shards have a cadmium folder including its code and everything is declared under a Cadmium module.

We'd like to generate a global website documentation API documenting everything contained into each of the cadmium shard.

I'll look into the code of crystal doc to see how it can elegantly be enabled (and hopefully can be made into a PR), but if you have any tips or suggestions, feel free to share !

[straight-shoota]

This feature actually already exists: You can pass Crystal file paths to crystal docs and it will add the folders where these files reside to the docs build paths.

For example, to include ngrams and graph in the documentation, you can run:

crystal docs src/cadmium.cr lib/cadmium_ngrams/src/ngrams.cr lib/cardmium_graph/src/graph.cr

This interface could be nicer, though. Maybe using an --include option which resolves paths like the require keyword and adds the referenced libraries to the docs build path (included_dirs).

crystal docs --include ngrams --include graph

[straight-shoota]

Related: #7904

[asterite]

Something to improve: it doesn't accept directories, only files. That's what si tried, it didn't work so I suggested opening this feature request.

[rmarronnier]

Thanks so much @straight-shoota for your much detailed and specific explanation. It worked ! :confetti_ball:
I really like the --include option. Maybe crystal docs --include ngrams graph would be even better (less verbose) ?

[watzon]

It would be really nice if there was an option to generate documentation for included shards as well, or maybe be able to pass in a list of modules/classes to include/exclude

[straight-shoota]

@watzon Yeah, maybe it would be better to specify namespaces to include instead of file paths. That way it wouldn't matter where the source code comes from (which could be several distinct paths see #8553).

Depending on the use case, path based selection might still be useful, I don't know. At least the default should stay to include everything defined in src.

[watzon]

I think both could be useful. Sometimes you may want to include specific
paths, maybe if you have multiple projects that are related but don't
actually reference each other. In the case of Cadmium though, we have a
single "master repo" that imports all of the base shards. So it would be
pretty easy to just generate complete documentation from that project
itself.

On Wed, Dec 4, 2019, 1:48 AM Johannes Müller [e-mail]
wrote:

@watzon https://github.com/watzon Yeah, maybe it would be better to
specify namespaces to include instead of file paths. That way it wouldn't
matter where the source code comes from (which could be several distinct
paths see #8553 https://github.com/crystal-lang/crystal/issues/8553).

Depending on the use case, path based selection might still be useful, I
don't know. At least the default should stay to include everything defined
in src.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/crystal-lang/crystal/issues/8550?email_source=notifications&email_token=ABCTI7VC2RBJP42P4IAAYBDQW5VEDA5CNFSM4JU4N7ZKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEF4GKNI#issuecomment-561538357,
or unsubscribe
https://github.com/notifications/unsubscribe-auth/ABCTI7TCDSDILYQTMAAAGDLQW5VEDANCNFSM4JU4N7ZA
.

[asterite]

For included shards my idea would be to have an entry in shards.yaml saying where the docs are located (URL). Then when generating docs, types which are referenced from your code but are in external shards have a link to those URLs. Then we can have decentralized and interlinked docs too. But it really depends on users keeping links up to date and actually pushing docs somewhere.

[straight-shoota]

@asterite Yes, that could work, but there are also valid reasons for generating all-included documentation locally (for example when you want to browse documentation without internet access).

[straight-shoota]

What currently doesn't work with the approach I presented in https://github.com/crystal-lang/crystal/issues/8550#issuecomment-561358101 is linking to source code. Because that's fixed to the code location of the main shard. One option to solve that would be to provide source code url mappings to the doc generator that map paths to url pattern. Alternatively, for paths in lib/ the respective shard source location could be used. This could work automatically, but means the docs generator needs an understanding of shards, which adds a lot of complexity.