[racket-dev] A new Racket tool idea

Hey,

After some discussion about generating project documentation in Racket
on the users list, I thought to mention what kind of ideas I have had
for such a tool myself. I started a small prototype tool because I had
problems understanding the project structure of some of my Racket
projects. It's difficult to keep track of what you have.

What I have right now is simple parser for require-statements that goes
through a folder structure looking for Racket modules and their
requires, it generates a simple object structure that is then fed to
this tool that among other things has a Graphviz translator that creates
some graphs.

The end result is a static html site with some project information. At
the moment it contains only the module hierarchy and the types the
parser found. Ideally there would be a lot of stuff, documentation,
cross-references, searching. I included my sketch at the end of this
message.

The problem, besides having time to do everything, is that to do some of
these I need to either try to parse racket files myself or to hook into
Racket libraries that do it already. I expect there to be no easy API
for me to just start using to introspect Racket modules and code. There
are also undoubtedly countless difficult problems in perfect
introspection of such a flexible language as Racket is. For example,
what happens to everything in the presence of syntax errors or macros? I
don't intend this tool to be perfect but some easy low-hanging fruits
could be picked, I'm sure.

Is anybody interested in such a tool? I guess some people have similar
hacks that I have made so far. Can anyone point me to the right files in
Racket or perhaps in the documentation? And do you have ideas about the
feasibility of the features? What would be most useful? What would be
easy and what hard to do?

Hoping for some fruitful discussion :)
-Markku

----------

The kind of information I think this kind of tool would provide:

Project Name
- Status
- Sunny or cloudy, how the project is doing and activity level

Basic Information
- Welcome message
- Team
  - Project team, members and other stakeholders
- Source
  - Version control information, project site etc.
  - Browsable source, also linked to from other sections
- Documentation
  - Documentation extracted from source code / possibly comments

Modules
- What modules are in the project and their relationships.
- Provides
- How do units fit this picture?
- Support for PLaneT?

Types
- All structs and classes
- What other types?
- What can be done with Typed Racket?
- What about contracts?

Functions
- All functions
- What documentation can be extracted?
  - Tests -> examples
  - Contracts, types -> documentation

Tests
- All tests and their status
  - Support for BDD-like notation of documenting tests/code
- Coverage
  - Coverage of all tests

Metrics
- Code complexity, lines of code, file count, class count etc. metrics

Backlog
- Collected information about what needs to be fixed, errors and
warnings etc. Maybe based on metrics like complexity.
- To Do
  - Collected TODO comments
- Issues
  - Link to JIRA etc. issue management