A new documentation site Feb 2017

There’s quite a bit of new Forth code in the embello repository on GitHub, and more being added all the time - so it’ll become increasingly important that this code gets documented.

There are many tools to do this. To match the rest of JeeLabs, the preferred solution is a static site - that way access can be snappy, page overhead stays low, and local copies are easy to use.

At the same time, it’s also crucial that this information can be easily kept up to date and extended. If adding docs is tedious, it simply won’t happen…

The solution chosen for embello, is GitHub pages. Since the repository is already on GitHub, and since GitHub pages now supports documentation in a docs/ subdirectory (as opposed to a separate branch or repo), it has become trivial to maintain everything in one place.

Through the magic of a custom domain, and GitHub’s use of a CDN, the pages will be served by GitHub as well as many local mirrors, while being reachable through a very obvious url:

http://jeelabs.org

The main page shows a brief overview and explanation of how the embello repository is structured, and contain two areas with reference information: 1) a list of hardware boards frequently used on the weblog, and 2) the Forth Library Documentation, as shown here:

The list of entries is not very long yet, and the amount of information on each page is not very extensive either at this point, but it’s a start. The point is to get the basic mechanism rolled out so that the rest can grow organically in the coming weeks and months.

Anyone obtaining a git clone, ZIP snapshot, or TAR snapshot will also get a copy of the documentation in its current state. It’s all open source, and free for any use.

To avoid having to maintain information in two places, the API documentation is extracted from the actual Forth source files, which need to contain word definitions of the form:

: blah ( n1 n2 -- f )  \ brief description of blah

Variables and constants will also be extracted by this documentation tool, which can be found in the tools/docex/ area of embello. The result is a documentation site which is set up entirely in Markdown, offers snappy static page access, and should be easy to update and keep in sync with the actual code definitions. Missing and misspelled files & words will be caught by docex.

Another convenience, is that every git commit will automatically re-generate the site.

Creating (and maintaining!) documentation is a long-term task. Your help is most welcome:

• Please point out errors and missing docs by submitting a new issue on GitHub. Each mistake and omission deserves a fix, and will be given attention - with lots of tender love and care.

• You’re welcome to clone the embello repository for your own use, and to make changes or add new documentation, just like you would to get your own code added to the embello repository. The preferred mechanism to make this happen is to submit a Pull Request on GitHub.

• For discussion or any comments / tips about this documentation area, please visit the forum.

This is a step to help streamline the process of documenting it all. Search is not implemented by this static documentation site, but once it has been indexed a bit, you should be able to use a search engine by adding “site:jeelabs.org” to your search query.

Will embello prosper & flourish? Only time will tell. Will this help make it usable? Definitely.