introduce eelco, a doctester

[mightyiam]

No description provided.

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-08-10-documentation-team-meeting-notes-71/31558/1

[mightyiam]

The doctester app seems to fail when executed in the build phase. I'm guessing this has something to do with failing to creating a file that is part of creating a PTY.

Perhaps as a flake "check" this would be run in an environment that would allow such files to be created?

Can something be done otherwise to allow these files to be created?

[mightyiam]

Failure:
https://github.com/NixOS/nix.dev/actions/runs/5832308481/job/15817476652?pr=672#step:5:907

Relevant crate:
https://docs.rs/pty-process/latest/pty_process/index.html

[mightyiam]

Worked around this by making this a flake app, instead.

[mightyiam]

Regarding the fenced code block language tag, the following

```text nix-repl

would work, but it's not nice. I'd like to use the Sphinx API to create an extension that prepends text to nix-repl, avoiding the issue.

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-08-14-documentation-team-meeting-notes-72/31722/1

[mightyiam]

I can refine the implementation but that can be done later, as well. This is already useful. Therefore, asking for review.
A few hundred lines of Rust code. But you can also take the approach that it probably works and if it doesn't then @mightyiam will fix it.

[mightyiam]

I feel that there is some open source rust crate potential somewhere in this but haven't thought of where to draw that line yet.

[mightyiam]

Yes, there are no tests. I wonder whether anyone will insist on tests...

[infinisil]

We should consider moving the Rust project into a separate repository, it should also definitely have tests and code comments and somebody should take a somewhat closer look at the code.

[domenkozar]

Have you seen https://github.com/OceanSprint/tesh

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-08-17-documentation-team-meeting-notes-73/31853/1

[fricklerhandwerk]

Yes, and I don't know why we didn't start with integrating tesh to begin with.

[mightyiam]

It didn't seem to me like tesh provides the desired interface.

I'm in the process of extracting the vast majority of this PR into its own repo.

I suppose I will convert to draft. But I don't see the button. Are draft PRs disabled?

[mightyiam]

Well... today is the last day of https://thaigersprint.org/, during which I've been working primarily on this. The documentation example tester has been extracted and released. And I've updated this pull request.

All examples are skipped except for two. Those two are repl examples.

As it stands in this PR branch, repl examples and expression examples can be written and/or edited, as long as they're within the limited feature set of eelco. That is, channels cannot be used. Examples that consist of multiple files are not supported. Could be other things we wanna do that are not supported.

[mightyiam]

Should this be merged at this stage? Is it better than nothing? Is the design of eelco reasonable?

[fricklerhandwerk]

I still have to play with it to see how it behaves in case of errors. From the consumer perspective I'd expect it not to require changing anything about the documentation source though.

[fricklerhandwerk]

That is not an improvement because now there is no link to reference docs. It was good as it was.

[fricklerhandwerk]

Suggested change

Why is there an empty line?

[fricklerhandwerk]

Since you're only testing nix-repl blocks, there should be no need to spam every other block with redundant information (the purpose of which is not evident without "just knowing" what it means).