search

crystal-lang / crystal

The Crystal Programming Language
https://crystal-lang.org
Apache License 2.0
19.51k stars 1.62k forks source link

Multi folders crystal doc generation support #8550

Open rmarronnier opened 5 years ago

rmarronnier commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

Related: #7904

asterite commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

@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 commented 5 years ago

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 notifications@github.com 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 commented 5 years ago

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 commented 5 years ago

@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 commented 4 years ago

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.

oprypin commented 3 years ago

https://oprypin.github.io/mkdocstrings-crystal/ supports multi-folders, and even arbitrary inclusions/exclusions. https://github.com/athena-framework/website/ uses it: https://athenaframework.org/Routing/