extra files option for crystal doc

[noraj]

Feature Request

It would be handy to introduce a new option to crystal docs so that it would accept extra markdown (or text) files outside the default README.md like yard does.

This would allow to join extra files like a CHANGELOG.md, LICENSE, or any extra documentation that doesn't fit into the code like TODO.md, user documentation, etc.

The extra files would be listed on a new section on the left sidebar.

This also helps to avoid having to have an extra website for user documentation or just a few files separated from the code documentation.

Example

YARD sidebar listing extra files

Related resources

• Documenting code
• Using the compiler - crystal docs

[hugopl]

Maybe something like:

# @section ../doc/install.md

That would create a section (file) in the docs with the file contents interpreted as markdown, the title could be the contents of the first line if it's a markdown header or the file name if the first line has no markdown header.

The link to the generated page would go in the beginning of the sidebar.

Two section defined in different places with same title would be just appended one on another.

[nobodywasishere]

@hugopl I think going with what exdoc or yard do may be better, as having plain markdown would also allow viewing from github/etc, and would be easier to implement.

[hugopl]

Sure, I read again what I wrote and I agree with you, better do the simpler first and wait to see the needs from real world usage.

[straight-shoota]

Writing plain markdown files seems like a no-brainer.

But there needs to be an integration to let the doc generator know about those files.
The OP suggests an option to the crystal docs command. I'm not sure if that's a good idea because IMO this kind of information should be more static, i.e. embedded into the content, not the build command.

Ony way to to that could be some kind of configuration file for the compiler/doc generator. The benefit over CLI arguments is that this would be checked in as part of the repository. But there is currently no such thing and it still feels more like this should be part of the content, not configuration.

Another option would be a kind of include mechanism as suggested in #13184 (comment)
In fact, you can actually already hack a similar functionality with macros:

macro embed_documentation(file)
  {% if flag?(:docs) %}
# {{ read_file(file).gsub(/\n/, "\n# ").id }}
module Docs::{{ file.split("/")[-1].gsub(/\..*?$/, "").camelcase.id }}
end
  {% end %}
end

Of course, posing as a documentation module isn't ideal and this could be integrated more nicely. But hey, it works 🦾
And I think it's pretty decent.
This can work as a basis for improving things maybe a bit more, with additional support in the doc generator.

[noraj]

For info, crodoc tries to be the yard equivalent for crystal.

[nobodywasishere]

@straight-shoota I think that's cool and may work well, though I'm not sure it's the best solution as it requires any docs need to be passed in via the AST, when it could be much simpler to pass them to the docs generator itself. As well, these docs pages are meant purely for documentation for the user, instead of anything Crystal itself will ever use, and aren't necessarily directly related to any singular section of the code itself (though they could be).

I do think configuration is the right place to put this as it is configuration for the docs generator, telling it what files to generate and how. I think YARD's system of having a .yardopts works the best, perhaps we could have a .docopts, .crystaldoc, or .crystal-doc-opts with CLI options to pass to the docs generator. The other option is having the ability to pull from a shards.yml if it exists, but I could understand wanting to keep them separate.

[straight-shoota]

it requires any docs need to be passed in via the AST, when it could be much simpler to pass them to the docs generator itself.

I don't understand what you mean here, could you expand a bit on that?
There would be independent documentation files and the embed_documentation macro (or a built-in alternative) would just pull them into the source code in order to make them available to the doc generator. The generator needs to parse Crystal source code anyway, so I don't see any additional overhead.

[nobodywasishere]

It's not source code, and I think the implementation could be a lot easier (and it easier for people to use/figure out how to use it) if it were via CLI args. It wouldn't require any changes to the compiler itself, nor using a special module (which may lead to its own problems if someone is already using that module name for other purposes).

[crysbot]

This issue has been mentioned on Crystal Forum. There might be relevant details there:

https://forum.crystal-lang.org/t/updates-in-the-athenaverse-windows-support-and-deja-vu/6753/1