Documentation

New Content

There's a lot of undocumented or under-documented libraries that should be documented in the Library Reference.

Other libraries also need documenting outside of the Library Reference, like the HTTP libraries.

Cheat Sheets

• Table operations
• Exception handling (block/exception and let handler)
• String formatting operations
• Testworks

Improve ePubs

The ePubs need some love, some of which probably requires improvements to Sphinx itself. The improvements should include:

• Better title / cover pages.
• Correct versioning.
• Better handling of copyright info.
• Better CSS / colors / formatting of the text, especially code blocks.

Improve PDF Output

This may require changes to Sphinx as well. Our API documentation is currently formatted in a pretty specific way in HTML and that isn't handled well in the PDF output.

• Annotations on definitions (like 'Method', 'Function', 'Generic') aren't right aligned.
• Field lists aren't structured very nicely.
• The underline that we have under the API names in the HTML is missing in the PDF output.

Improve Sphinx Extension

The Sphinx extension that we wrote and use for doing Dylan API documentation needs some improvements:

• Support .. type:: and a type role.
• Move summary text into a summary keyword, but maintain existing display. This would let us have the summary available via tools once we do JSON output from Sphinx.

Publish to Dash

Dash is a browser for API documentation. With some work, we can publish our documentation as docsets for Dash. We can probably use doc2dash for at least part of this process.

When this is done, we should try to get an entry for Dylan added to the Sublime Text mappings.

Build Windows Compiled Help

What's involved in building CHM files from our docs?

• We will need a customized theme with no JavaScript.

Documentation Generation and Extraction

We currently have a way to export skeletal documentation from a library in dylan-compiler. It has some issues:

• Class names are fully scoped in cases where they needn't be. (Especially dylan:dylan.)
• Type info on init keywords?
• Separate file per module?
• How should we best format the signature? (DRM style, current style, etc.)
• Are #rest and #key parameters getting flagged correctly?

We'd also like to one day support extracting textual documentation from the Dylan source code. We currently throw away comments during lexing, so there's some work to do to enable this:

• Don't throw away comments during lexing.
• Store them with the correct definitions.
• Be sure they're getting into the DOOD files.
• Modify the generation tool to take this into account.