11 Project Documentation and Revisions🔗

Due: April 21, 11:59pm.

Your last task is to document and package your DSL for users and potential contributors. This includes:

• An info.rkt to make your repository a Racket package

• A README

• Reference documentation written in Scribble

Your documentation can update and adapt the content you previously wrote as your design document for HW 7.

As an example, I documented and packaged the PEG DSL we developed in class: https://github.com/michaelballantyne/minipeg

You should also revise your implementation according to the feedback you received at your code walk.

11.1 info.rkt🔗

Create an info.rkt at the root of your repository to inform Racket’s package management tool about your code’s dependencies and documentation. This makes it easy for others to get your code running. Here’s what the info.rkt for my minipeg package looks like:

Once you have an info.rkt, you should be able to install your package and any needed dependencies by running

at the root of your repository.

After modifying code, you can use,

to recompile any updated code, and you can run tests for all modules in your repository with

The file exporting the public interface of your DSL should be named main.rkt at the root of the repository. This is the module that will be accessed when users install your package and (require your-package-name).

Conventionally, modules that user should not access directly are placed in the private directory within a package.

11.2 README🔗

At a minimum, your README should:

• Tell potential users why they might be interested in your DSL, i.e. a purpose statement for the DSL and description or links to relevant background information necessary to understand the domain.

• Whet their appetite with a small but compelling example. Point out how the benefits of your DSL show up in the example.

• Provide instructions for installing the DSL and accessing the full documentation

See my minipeg README as an example: https://github.com/michaelballantyne/minipeg.

11.3 Scribble documentation🔗

Update and adapt the grammar, signatures and purpose statements from your design document into reference documentation using Scribble in a file at scribblings/main.scrbl.

Here’s what a minimal Scribble file looks like:

One way to build the Scribble file into HTML documentation is to open it in DrRacket and press the "Scribble HTML" button. Note that this will create a bunch of HTML, JS, and CSS files adjacent to your main.scrbl file, so you might want to add scribblings/*.html, scribblings/*.js, and scribblings/*.css to your .gitignore

Another way is to run

to recompile the code in your package and rebuild the documentation. Then you can open the documentation with:

In the example file above, the for-label require makes names available to refer to in the racket form, which creates linked references to their documentation.

The defform form is used for documenting macros. You can specify grammatical structure as well as contracts for Racket expression positions in the grammar. The defproc form is for documenting procedures exported by your DSL and their contracts.

See the Scribble documentation for minipeg for examples of other Scribble features you may want to use, such as including example code and creating linked references to technical terms: https://github.com/michaelballantyne/minipeg/blob/main/scribblings/main.scrbl

If your DSL has a static semantics beyond basic grammar checks, this deserves a high-level description in its own section of the documentation.

11.4 Developer documentation🔗

Beyond documentation targeted at users of your DSL, you should provide documentation explaining the structure of the implementation for the benefit of your future self or other potential contributors.

Signatures, purpose statements, and examples for the functions and macros in your implementation provide the first level of documentation.

However, a DSL typically has additional high-level struture. Its implementation may consist of multiple compiler passes that implement static checks and optimizations before generating code using a runtime system. Each of these compiler passes may consist of multiple macros working together towards a common purpose. This overview deserves documentation as well.

In private/README.md, provide a guide to the high-level components of your implementation and the files in which they are found. Depending on your DSL, it may also make sense to illustrate the steps of compilation here with example programs representing the intermediate output of each step.

Link to this documentation from the main README.

11.5 Revisions based on code walk feedback🔗

Finally, make sure you’ve revised your implementation and documentation based on feedback you received in the code walk. You should have received an email from me with particular revisions I expect to see included. In your submission, explain each change and include a link to the commit that realizes it.

11.6 Submission🔗

Make sure your repository is public. I plan to link to all the project repositories from the course web page. I might also link to some from syntax-spec documentation as examples, though feel free to let me know if you would prefer I do not.

Create a PDF containing a link to your repository together with the descriptions and commit links for the revisions you made based on code walk feedback.

Submit to Gradescope, in a group submission with your partner: https://www.gradescope.com/courses/941020/assignments/6081816