dhall-docs input as expression

[german1608]

Following my schedule, after finishing with #1991 I should either:

• Add JTD on imported expressions
• Add type-on-hover

...but something really cool that I want to add is to drop generating documentation from an input package, but from a dhall expression. Something like this:

# from a local file
dhall-docs --input "./package.dhall"
# from any expression
dhall-docs --input "{ a = foo, b = bar }"
# from an URL
dhall-docs --input https://prelude.dhall-lang.org/package.dhall

The behavior of how to generate docs would change depending on what expression was passed down:

• If the amount of imports in the full normalized expression is greater than 0, then a directory-tree will generated with the collected imports
• Otherwise, a single documentation file will be generated, by analyzing the input expression

By doing this, we remove the constraint of having the .dhall extension, which I don't like a lot in principle, because it doesn't always resemble to what the dhall package contains (probably you have a cool hidden feature without the .dhall extension). In addition, generating documentation from a URL would be really cool.

But I won't have time to do this and the remaining tasks of my schedule in the last 2 weeks of the program. And although I can (of course) keep contributing to Dhall after the project ends, I'd like to see what you think about what has a higher priority between this issue and the remaining of the scheduled features

I'm aware that this would be a breaking change, but I IMO is worth to take the risk

[sjakobi]

• Add JTD on imported expressions

Could you give an example of this feature?

• Add type-on-hover

This sounds like a really cool feature to me. If you can make progress on this during the remaining time, I'd like to see that.

Regarding the feature you're proposing here, I think it sounds cool, but not as valuable as type-on-hover. Maybe I don't see the benefits very clearly yet. Regarding the current restriction with the .dhall extension, I'm not very worried about it since I expect the ecosystem to standardize on using that extension.

I'm aware that this would be a breaking change

Can you clarify what that breaking change is?

[german1608]

Could you give an example of this feature?

That would allow us to jump to the definition on other files

(./package.dhall).foo

Regarding the feature you're proposing here, I think it sounds cool, but not as valuable as type-on-hover. Maybe I don't see the benefits very clearly yet.

The main benefit would be to generate the docs from a remote source. Say you want to generate the docs for Prelude for offline development, by running dhall-docs --input http://prelude... you get the latest docs.

Regarding the current restriction with the .dhall extension, I'm not very worried about it since I expect the ecosystem to standardize on using that extension.

OK. Now thinking, this standard we're defining for dhall-docs could be reused for, say, a hackage for dhall

Can you clarify what that breaking change is?

Well, the command would change the ---input flag to receive the dhall expression instead of the folder.

[german1608]

Since the best profit of using dhall expressions as input is to generate docs for remote sources, what we can do instead is to add another flag, say, --remote, that downloads the files from an URL and generates the docs from there

[Gabriella439]

I don't have strong opinions about the priorities. I would be happy with any one of these three features. If I had to pick one, I would slightly prefer jump-to-definition for imports since I think easily accessing the relevant source code is important for code comprehension.

[sjakobi]

I would slightly prefer jump-to-definition for imports since I think easily accessing the relevant source code is important for code comprehension.

I'm also fine with this.

[german1608]

I'll give an update here, since it's still open :)

I'm working on the JTD on imports, but the implementation is getting a little complicated, and I don't have something solid to show you in a draft PR yet. I'm thinking that taking the dhall-docs input from an expression and collecting all imports founds in the resolution might make the implementation easier. I'll try that to see how it looks.

If you're wondering, what I'm trying to do is to create a graph of dependencies between the collected files in a folder by using Dhall.Import utilities, specifically the _graph field from Status. I'm having problems in code organization: I try to keep all the core logic in pure components, and all utilities I want to use from Dhall.Import are build on top of IO. From the graph (a DAG, specifically) I create a topological sort, and I'd use that order to render the source code keeping the final JtdInfo on each file.

I'll try to keep you updated about my progress