docs.gl rebuilds the OpenGL manual as static HTML

The framed Khronos site is the problem being solved

docs.gl exists because of a specific complaint about the official OpenGL documentation. The project description says the documentation website provided by Khronos is in frames and poorly formatted, difficult to navigate and search, and that docs.gl aims to improve the form factor and quality of that documentation. The output is described as a public domain web scaffolding for the OpenGL documentation.

So the user is a graphics developer who already knows which command they want, for example a texture binding function, and who is frustrated by navigation rather than by content. The content itself is Khronos text. The contribution is presentation, structure and search behaviour.

The project is also positioned as a public wiki backed by GitHub: pull requests are the mechanism for improving the documentation, and the description asks contributors to submit one if they find functionality missing. That framing matters for how you evaluate it, because it is a fork and a reformat of somebody else's manual rather than an independent reference, and the pages it serves still describe the same API that the vendor documents.

compile.py does every transformation at build time

The architecture is deliberately old school. docs.gl is a Python script that reads each man page, processes it and outputs static HTML. There is no database and no server side scripting. All of the templating and processing is done at build time by the script.

That single decision shapes everything else about the project. The published site is a folder of files, which means it can be served by any static host, mirrored, or opened from disk, and there is no runtime to patch when something goes wrong. It also means that every piece of derived information, such as which version of the API a command belongs to, has to be computed while the site is being built rather than queried when a reader loads a page. The project accepts that cost, and the token mechanism described below is the workaround.

The output lands in a folder named `htdocs` once the script finishes building. Readers of the code should note that the repository also carries `server.py` and `server.sh` alongside the offline viewer script, but the description of the build itself makes no mention of any server component being needed to produce the site.

Template tokens carry the version data that a live site would query

The `html` directory holds further resources for compiling the site. Files sitting directly in it are template files used to further process the manual pages, and inside those templates are tokens that compile.py searches for and dynamically replaces during compilation.

The example given is `{$current_api}`, which is replaced with `3.3` or `4.2` depending on the latest version that the command being compiled is available for. All content on the site that changes based on which manual page is being compiled is handled this way, which means the version logic lives in the templates and the data tables rather than in a request handler.

A second token mechanism appears in the `examples` folder, where the source code examples used in the manual pages live. A special token such as `{%glBindTexture}` produces a link to a command page, and the link target is rewritten depending on whether the example appears in a GL4 page or a gl3 page. That means cross references between code samples and reference entries are resolved at build time and stay correct across the different API versions the site covers.

The `copy` folder is simpler: files there are used without changes.

Building the site takes one command and two optional flags

The build is run from the project root with a plain Python invocation:

	python compile.py

That produces the static site in the `htdocs` folder. When you are preparing a final release, the `--full` parameter adds HTML minification and Unicode processing:

	python compile.py --full

If you want a copy that can be used offline, the `--local-assets` parameter downloads the fonts and Javascript libraries and then builds the HTML and CSS using those local copies:

	python compile.py --local-assets

That last flag is the one that matters for reading the documentation on a machine with no network access, and it is also the flag required before the offline viewer will work. On Windows the repository provides `build.bat` and `build_full.bat` for convenience, which wrap the same script.

What you should see after a successful build is the generated site directory, and nothing running in the background. No service needs to be started to read the pages, since there is no server side component to host.

Offline viewing runs a local server on port 8000

Reading the locally built site in a browser takes one extra step. The description says to compile the files first with the `--local-assets` flag, then, while in the root project directory, run `python start_offline_webserver.py`, which starts a local webserver on port 8000. You then open `http://localhost:8000` in your browser.

The reason a webserver is needed at all, in a project with no server side scripting, is that the generated pages reference local font and Javascript assets, and browsers often refuse to load those over a plain file path but load them fine over HTTP. That is the practical reason the `--local-assets` flag exists at all, since it rewrites the references to point at the downloaded copies.

Note the constraint on the port. If something else on your machine already listens on 8000, the viewer will not start cleanly, and the documentation does not describe a way to change the port from the command line. That is a small annoyance, but it is the kind of detail worth knowing before you plan to run the viewer in a shared development environment.

Eight manual directories and a set of one time processing scripts

The manual pages live in eight directories named `el3`, `sl4`, `es1`, `es2`, `es3`, `gl2`, `gl3` and `gl4`, one per API family and version. The description is precise about their contents: they hold only the inner HTML with header and footer elements such as `head` and `html` stripped out. The stripping is not cosmetic, because compile.py injects the template structure around each page, which is why the vendor header has to be removed first.

The top level of the repository also holds a family of helper scripts. `opengl.py` and `glsl.py` contain helper tables, for example which commands appear in which versions, tables specifying which examples should appear on which pages, and tables specifying the categories that appear in the table of contents of each page. `insert_additional.py`, `make_copyright.py` and `strip.py` are described as special one-time-use programs that were used to process the manual pages after they were initially downloaded from Khronos, though the description adds that they could be reused for additional processing.

One script is part of the regular cycle. `read_spec.py` reads the XML OpenGL spec file found in `specs/gl.xml` and outputs `opengl_spec.py`, which contains the raw data on which commands belong to which versions. The description notes that `opengl_spec.py` should only have to be regenerated when Khronos updates the spec, which tells you exactly when the version tables go stale.

The To Do list is the honest description of what the site does not show

The project publishes its own backlog, and reading it is the fastest way to understand the gaps in the site you are about to use. The listed items include displaying a list of which versions an extension is available for and which extension introduces a command, displaying on each page a core in version or core since version line like the OpenGL Wiki does, integrating the common mistakes file into the page for each command it pertains to, and showing on each page which commands are likely to cause a pipeline stall, with glGet given as the example.

Further items include marking in the table of contents which GLSL commands can only be used in certain languages, a CamelCase search where BFDLI finds glBindFragDataLocationIndexed, GLSL 1 and 3 support, WebGL, and GLSL syntax cheat sheets comparing attribute and varying with in and out.

Two of these deserve a note from a reader's perspective. The pipeline stall markers are the item most likely to change how you write code, since a page that warns you that a command will stall the pipeline is different from a page that only describes its parameters. The CamelCase search entry shows that the search behaviour advertised as an improvement over Khronos was still incomplete, and the GLSL language restriction markers would matter most to shader authors. The repository also carries a `todo.md` file at the top level alongside the list in the readme.

A custom licence, no releases, and a last push in April 2026

The project listing records the licence as Other, described as a custom licence that GitHub cannot classify, with a pointer to the LICENSE file. The top level entry list for the repository does not show a LICENSE file among its contents, so anyone intending to reuse this scaffolding should read the licence text in the repository before redistributing the generated site or the templates.

On the question of upkeep, the honest answer is that this is a project that stopped moving rather than one that is being actively tended. The repository is not archived, and the last push was on 2026-04-12. There are no GitHub releases, so there is no tagged version to pin a deployment to, and no changelog to consult for what changed between builds. The build flags are stable enough to run, but the content tracks a Khronos manual snapshot of some date, and the docs description does not say which one.

For a personal reference site, that is a small cost. For a documentation pipeline inside a company, the practical upgrade path is to run compile.py against a fresher copy of the man pages yourself and accept the custom licence terms of the scaffolding.

Editorial conclusion

Use BSVino/docs.gl if you want a clean, offline capable copy of the OpenGL reference pages and are comfortable running a Python build over the vendored man pages. Do not treat it as a live documentation service, because there is no database, no server side scripting and no tagged release to deploy against. Before depending on it, run python compile.py --local-assets and confirm the generated htdocs folder matches the OpenGL version your project targets, and check the custom licence in the LICENSE file because the repository uses a licence arrangement GitHub cannot classify.

Frequently asked questions

Official sources

1. BSVino/docs.gl on GitHub
2. Issues
3. README