New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation tests #465

Closed
tiehuis opened this Issue Sep 11, 2017 · 10 comments

Comments

Projects
None yet
2 participants
@tiehuis
Member

tiehuis commented Sep 11, 2017

Summarised from here #452.

  • Move docs from https://github.com/zig-lang/www.ziglang.org to this repo
  • Make the docs a template that gets processed by a tool written in zig that looks for special "example" code blocks, also with metadata saying whether they should have a compile error, or succeed with tests, or whatever.
  • While we're at it, make the table of contents auto generated.
  • Run the doc generating tool along with the tests, and have it crash if example code has an unintended effect.
  • Do it for the homepage too
@tiehuis

This comment has been minimized.

Member

tiehuis commented Sep 11, 2017

Instead of performing rudimentary text processing just yet, one thing I was thinking of was to run pandoc on the output and get all code blocks. We can tag code blocks with an attribute like test-should-compile test-should-fail and for each of the blocks run the test command and check the result of the compiler.

We can match the compilation output against test-output blocks that should come after any with the above attribute.

This is a pretty hacky approach and I was messing around with this using pandoc and jq and it seems doable pretty quickly. Alternatively, use something like https://github.com/hoedown/hoedown and build a zig program around this. A bit more work here though and I need to check how/if we can attach attributes to code blocks if following this.

@andrewrk

This comment has been minimized.

Member

andrewrk commented Sep 11, 2017

I think if we didn't add any new dependencies I'd be up for this going into 0.1.0. If we want to make the build depend on more stuff let's push it to 0.2.0.

@tiehuis

This comment has been minimized.

Member

tiehuis commented Sep 12, 2017

I think we should aim for doing this without dependencies, but still for the 0.2.0 since it isn't a hugely visible change from the user perspective.

@andrewrk

This comment has been minimized.

Member

andrewrk commented Sep 12, 2017

Still for the 0.1.0 you mean? I'm ok with that.

@andrewrk andrewrk added this to the 0.1.0 milestone Sep 12, 2017

@tiehuis

This comment has been minimized.

Member

tiehuis commented Sep 12, 2017

I meant the 0.2.0, but I'll see where I get with this markdown parser and get back to you.

@andrewrk

This comment has been minimized.

Member

andrewrk commented Sep 12, 2017

Alright I'm ok with either, you can make the call.

@andrewrk

This comment has been minimized.

Member

andrewrk commented Sep 18, 2017

@tiehuis would you be terribly offended if I ignored the markdown pull request for now and made a tool in zig that did the above bullet points? I think it would be nice to only depend on zig once we have the compiler built.

@tiehuis

This comment has been minimized.

Member

tiehuis commented Sep 18, 2017

Not at all, go ahead.

I've started a markdown parser here but it'll be a while before it gets to the state of parsing the entirety of that file anyway.

@andrewrk andrewrk modified the milestones: 0.1.0, 0.2.0 Oct 16, 2017

andrewrk added a commit that referenced this issue Nov 7, 2017

std.io: introduce buffered I/O and change API
I started working on #465 and made some corresponding std.io
API changes.

New structs:
 * std.io.FileInStream
 * std.io.FileOutStream
 * std.io.BufferedOutStream
 * std.io.BufferedInStream

Removed:
 * std.io.File.in_stream
 * std.io.File.out_stream

Now instead of &file.out_stream or &file.in_stream to get access to
the stream API for a file, you get it like this:

var file_in_stream = io.FileInStream.init(&file);
const in_stream = &file_in_stream.stream;

var file_out_stream = io.FileOutStream.init(&file);
const out_stream = &file_out_stream.stream;

This is evidence that we might not need any OOP features -
See #130.

scurest added a commit to scurest/zig that referenced this issue Nov 8, 2017

std.io: introduce buffered I/O and change API
I started working on ziglang#465 and made some corresponding std.io
API changes.

New structs:
 * std.io.FileInStream
 * std.io.FileOutStream
 * std.io.BufferedOutStream
 * std.io.BufferedInStream

Removed:
 * std.io.File.in_stream
 * std.io.File.out_stream

Now instead of &file.out_stream or &file.in_stream to get access to
the stream API for a file, you get it like this:

var file_in_stream = io.FileInStream.init(&file);
const in_stream = &file_in_stream.stream;

var file_out_stream = io.FileOutStream.init(&file);
const out_stream = &file_out_stream.stream;

This is evidence that we might not need any OOP features -
See ziglang#130.

andrewrk added a commit that referenced this issue Jan 17, 2018

andrewrk added a commit that referenced this issue Jan 17, 2018

@andrewrk

This comment has been minimized.

Member

andrewrk commented Jan 17, 2018

I have this working and integrated into the build system. It generates the table of contents and the "see also" sections, but I haven't made it do code snippets yet.

I'm thinking something like this:

{#code|id_name#}

And then we'd have a table of id_names mapped to source code snippets with metadata.

Or maybe even allow embedding it:

{#code_begin|test#}
test "aoeu" {

}
{#code_end#}

{#code_begin|exe|hello#}
pub fn main() -> %void {}
{#code_end#}

{#code_begin|error#}
test "initialization" {
    var x: i32;

    x = 1;
}
{#code_end#}
@tiehuis

This comment has been minimized.

Member

tiehuis commented Jan 17, 2018

Great! Embedding would be great. I see the snippets anyway as first and foremost documentation, the testing is just to ensure they are always up to date. We would have a lot anyway and it'd save context switching.

andrewrk added a commit that referenced this issue Jan 17, 2018

andrewrk added a commit that referenced this issue Jan 17, 2018

ziglang.org home page no longer in this repo
update docs examples which use build-exe to be tested

See #465

@andrewrk andrewrk closed this in ea623f2 Jan 19, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment