Offline documentation

Over the holidays I've been doing more recreational programming on my laptop in places with spotty internet.

I've written a handful of scripts to manually sync source code with my desktop when I'm home but when I'm travelling I often need to do a quick lookup of something like the list of pathlib methods and offline documentation is frustrating.

Python can do introspection but it's annoying and not as readable as the online docs:

In [1]: import pathlib

In [2]: pathlib.__doc__

In [3]: print(pathlib.__doc__)
None

In [4]: from pathlib import Path

In [5]: print(Path.__doc__)
PurePath subclass that can make system calls.

        Path represents a filesystem path but unlike PurePath, also offers
        methods to do system calls on path objects. Depending on your system,
        instantiating a Path will return either a PosixPath or a WindowsPath
        object. You can also instantiate a PosixPath or WindowsPath directly,
        but cannot instantiate a WindowsPath on a POSIX system or vice versa.


In [6]: help(Path)
<finally some useful information>

You can also use pydoc to run an html server on a local port but the results are the same:

pydoc3 -p 1234

Looking online for other sources of offline documentation led me to devdocs. This is a website that lets you 'install' documentation for various programming languages for later reference. I was dubious about their claims that you could visit the URL even when you don't have working DNS but it worked on my laptop. Their FAQ explains how it works:

So basically magic. You know, the black kind that makes me wonder how many advertisers are using this to track everything I do, even when air-gapped. Still, it's a cool hack.

The mozilla developer network has a nice github repository with all their web documentation. If you do a shallow clone it's 271M of markup that compiles to html as you browse. To get this run:

git clone https://github.com/mdn/content mdn_content --depth 1
cd mdn_content
yarn start

I think there's more than enough for me here to look up all the weird markup rules for html but it can be hard to parse.

The gold standard of offline documentation is rust. In addition to thinking very hard about the deployment and reproducible build problem, they also seemed to have applied the same attention to documentation. The same utility that downloads or updates your compiler version will launch a page in your browser with documentation for your current version, using all the markup you find online:

rustup docs

The first page contains links to 10 free books with just about everything you'd want to know about the rust infrastructure.

Know you want something in the standard library? Just add an argument:

rustup docs --std

Just need to look up something in the book?

rustup docs --book

Every time I return to rust I'm pleasantly surprised.

posted by na on December 14, 2021 17:35