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

So You Can Dexy While You Dexy: Early Documentation Automation Work #1586

Merged
merged 30 commits into from Jul 20, 2014

Conversation

Projects
None yet
2 participants
@Shadowfiend
Copy link
Member

Shadowfiend commented Jun 20, 2014

This PR does three big things:

  • Introduce documentation for CSS selector transforms in the doc/ directory. This is in the
    asciidoc format.
  • Introduce dexy for automating documentation builds. The current configuration is very
    preliminary, and we'll probably want to be running things like API doc generation through there
    soon.
  • Add some helper stuff that lets dexy verify the examples in the CSS selector transforms
    are correct.

That last bit is the big one. There is a series of examples at the very beginning of the CSS
selector docs, and they are presented as input, CSS selector transform, output. There is a
Scala helper (ExtractCssSelectorExamples) that reads the compiled document (once it's
been compiled to HTML), extracts the input/transform/output triplets, and generates a fully-
functioning specs2 specification from them with one specs2 example per documentation
example. When you run dexy, it will compile the document to HTML, run the extractor,
and then execute the specification. The build will fail if there are errors in the spec.

The documentation is emitted into target/docs/, but it can also be viewed as rendered by
Github at https://github.com/lift/framework/blob/so-you-can-dexy-while-you-dexy/docs/css-selectors.adoc .

Shadowfiend added some commits Jun 2, 2014

Add some more general details on CSS transforms.
This includes the fact that they’re just
(NodeSeq)=>NodeSeq.
Do basic example extraction from dexy using Ruby script.
Not doing anything with the extracted examples yet, but this gives us the
starting point from which we can look at how we can read in a file, find the
examples in it, and run them. Ultimately, we're going to want to do this all
in Scala with CSS selector transforms, because hey, why not.
Add extract-css-selector-examples bash runner.
We use it to fire off the documentation helpers' ExtractCssSelectorExamples
application. Currently it's just a stub, more to come on that front.
Add selector class to selector examples.
We’re going to be using this to extract the selectors.
Extract CSS selector examples.
We’re not doing anything with them yet, but we’re extracting
the input, output, and selector function.
Fix dexy invocation of selector example extractor.
We now want to be passed the directory that the built HTML
is in, and we also have to compute it.

Additionally, we make use of the DEXY_ROOT environment
variable that dexy sets for us to know the project’s root
directory for proper invocation of sbt (we were computing this
in a somewhat brittle way before).
Drop extract-contents Ruby prototype.
It was just getting started, but we’ll be doing things with Scala
and Lift thanks ;)
Generate tests from documentation examples.
We generate them as files in the documentation-helpers
sbt sub-project, which can then be used to run them. Currently
the examples don’t compile yet, more to come on that front.
Dexy runs generated tests for selector examples.
We rename the example-verification target to
example-extraction, and make example-verification a target
that runs its own shell script.
Add support for setup code for example extractor.
This setup code is a code block marked with a .setup class.
Fix structure and matching in extracted tests.
Because of how HTML parsing works, we need to guarantee
a root node, so we wrap the input and output in a div. Then,
we include the div in the comparison we do after the fact.

We also compare rendered input to output ignoring
whitespace.
Fix CSS selector example docs based on tests.
First errors caught by test failures during documentation
generation! :)

@Shadowfiend Shadowfiend changed the title So You Can Dexy While You Dexy So You Can Dexy While You Dexy: Early Documentation Automation Work Jun 20, 2014

Produce CSS selector example specs for 2.11.
We need to mix in XmlMatchers to the Specification for the appropriate version
of specs2 to take.
@Shadowfiend

This comment has been minimized.

Copy link
Member Author

Shadowfiend commented Jul 2, 2014

Will probably merge this by the end of the week if no one has any strong objections, as it's not particularly invasive to the actual code base.

Shadowfiend added a commit that referenced this pull request Jul 20, 2014

Merge pull request #1586 from lift/so-you-can-dexy-while-you-dexy
So You Can Dexy While You Dexy: Early Documentation Automation Work

This PR does three big things:
 - Introduce documentation for CSS selector transforms in the doc/ directory. This is in the
   asciidoc format.
 - Introduce dexy for automating documentation builds. The current configuration is very
   preliminary, and we'll probably want to be running things like API doc generation through
   there soon.
 - Add some helper stuff that lets dexy verify the examples in the CSS selector transforms
   are correct.

That last bit is the big one. There is a series of examples at the very beginning of the CSS
selector docs, and they are presented as input, CSS selector transform, output. There is a
Scala helper (ExtractCssSelectorExamples) that reads the compiled document (once it's
been compiled to HTML), extracts the input/transform/output triplets, and generates a fully-
functioning specs2 specification from them with one specs2 example per documentation
example. When you run dexy, it will compile the document to HTML, run the extractor,
and then execute the specification. The build will fail if there are errors in the spec.

The documentation is emitted into target/docs/, but it can also be viewed as rendered by
Github.

@Shadowfiend Shadowfiend merged commit 3bf8359 into master Jul 20, 2014

@Shadowfiend Shadowfiend deleted the so-you-can-dexy-while-you-dexy branch Jul 20, 2014

@fmpwizard fmpwizard added this to the 3.0-M2 milestone Jul 23, 2014

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