The next thing I need to tackle, really, is ticket [3514e65] — Series pages.
However, I’ve been away from the source code for a bit and find myself needing a refresher before I do that one.
So I’ve decided to focus on another task: building the Scribble documentation for the code I’ve written so far. This is a great fit for where I’m at now, because it can be done in small spurts, it’s rewarding because it looks cool, and it serves as a much-needed bank of cognitive effort that will pay off as I build on the foundation I started and things get a bit more complicated.
Scribble is the best code documentation system I have yet seen. It cross-references everything to everything, its structural demands expose gaps in your design and thinking while you’re writing it, and it just plain looks good. (When I reskinned this repo my goal was to get it visually in line with the styles used by the Scribble documents I knew would be coming later.)
You can see this evolving in real time in the Code Docs section of this repo. As I edit the Scribble docs in the code-docs folder, I update the HTML output live on this site pretty much continuously so I can check my work. To reduce timeline churn, I only check in the changes to the original .scrbl files themselves in very large hunks.
I’ve never seen Fossil and Scribble integrated anywhere else, but they go together very well. If you specifically want to understand that integration, here's what to look at:
- I’m storing and serving the HTML/CSS/JS output of Scribble as “unversioned” files in the
scribbled/subfolder. That subfolder is also part of the repo’signore-globsetting. - Check out the
scribbletarget of themakefile. This shows you the sequence of commands for rebuilding the HTML docs, adding them to the repo as unversioned files, and syncing these unversioned files to the remote repository on the server (the one you’re looking at now). - Look at the
code-docs/scribble-iframe.htmlfile; this file is version-controlled, but also gets copied to scribbled/ and added to the unversioned files group. It contains an<iframe>tag that loads up the Scribble documentation - I had to edit the skin for the repository’s web UI to add a navigation button for the Code Docs section, add CSS to correctly position the iframe to fill up the page propperly, and finally to edit the content security policy (via a
<meta>tag in the HTML’s<head>section) to allow links into the main Racket documentation atdocs.racket-lang.org. - Finally, in
code-docs/scribble-helpers.rkt, I made a few custom convenience Scribble functions to allow easy linking to tickets and wiki pages in this repository, or to pages on external sites. This was partly necessary because, for links from inside the<iframe>to work, you need to add thetarget="_parent"attribute to the link (ortarget="_blank"if doing an external link, due to the content security policy), and the Scribble code for doing this is annoying if you have to type it more than once.
If, despite your interest in this topic, these pointers still seem a little inscrutable, just go out and try setting up a Fossil repo and with integrated Scribble docs like this one. You’ll run into obstacles. Then the stuff above will make a lot more sense.