Lever documentation came online

I did not like the python documentation generator so I decided to write my own documentation tools for Lever. Now I finally have the first results. The latest Lever documentation is online now.

screenshot

Last time, when trying to document by language using sphinx I ended up disliking about everything in it. I defected to plain text files shortly after my few first reStructuredText files.

Documentation is hard, and you have to repeat yourself a lot when you create the manual, references, tutorials, examples. Somehow the people who made Python's documentation tools thought that it's okay if we put the author to repeat himself a little bit more. Docstrings look like a good idea until you actually have to document something.

Flow of documentation

When I was writing my documentation into plain text files I realised that doing so was actually very natural:

Each document requires that the documents created before it cover the subject. This kind of upwards workflow from the code is effortless and keeps the documentation comprehensive.

Comments

Comments are the first line of documentation after the code. In teaching material they are usually used to explain what each line is doing.

In practice comments should never explain things that the code can explain alone because it cheapens their actual purpose of pointing out surprises and explaining why the code was written in the first place.

Comments are always written as if you expect that the person reading the comments also reads the code.

Modules map to documentation files

Lever's documentation is built around a concept that a single file is both the user manual and a reference. The file is processed to get the appropriate views for each use.

As the practice is to also document the internals, the internals are either documented in the same file, or then there's an another file in the documentation directory.

The files have fairly free structure. Each module has a 'doc' attribute that should point out the file that documents the module.

Bidirectional

Lever's documentation system is bidirectional. The runtime is capable of both writing and reading the documentation files.

This kind of arrangement makes it easier to keep the documentation updated. The runtime can load the correct reference on demand. It also can check whether the documentation is up-to-date, do the appropriate rewrites and appropriate documentation stubs for new functions.

Source links

The documentation is riddled with things like this:

{
    "source":"builtin:/stdlib/api.py",
    "start":{"col":null,"lno":201},
    "stop":{"col":null,"lno":205}
}

These allow the reference documentation linked to where the function is implemented. It is done with the hopes that more people would actually read the source, but it is also helpful for people writing the documentation.

Searchable reference

One last fancy thing you may notice that in the documentation index you see a button that says 'reference'. It provides a link and a summary to every function that is available in Lever.

"XKCD 927"

If you plan to quote a certain comic, I have to inform you that the Texopic language and the documentation system built upon it has been designed for specific usecase. It is not an universal standard for anything and you do not need to support it, unless you, of course, read or write Lever's documentation files for some reason.

Work in progress

Now.. While writing this I am still not done with the representation of all the information in the documents.

I get it right soon enough though.

Similar posts