https://github.com/foreverzer0/gldoc
Local HTTP server for hosting the official OpenGL documentation in a simplfied JSON format.
https://github.com/foreverzer0/gldoc
documentation documentation-generator documentation-tool go golang opengl opengl-es opengles rest-api restapi
Last synced: 2 months ago
JSON representation
Local HTTP server for hosting the official OpenGL documentation in a simplfied JSON format.
- Host: GitHub
- URL: https://github.com/foreverzer0/gldoc
- Owner: ForeverZer0
- License: mit
- Created: 2024-04-01T03:33:00.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2024-04-02T02:42:50.000Z (about 1 year ago)
- Last Synced: 2025-01-31T12:33:26.590Z (4 months ago)
- Topics: documentation, documentation-generator, documentation-tool, go, golang, opengl, opengl-es, opengles, rest-api, restapi
- Language: Go
- Homepage:
- Size: 15.6 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# GLdoc
GLdoc hosts a local server that returns OpenGL documentation parsed from the [OpenGL-Refpages](https://github.com/KhronosGroup/OpenGL-Refpages) in a simplified JSON interface, which can then be read and used from any language using only basic HTTP requests.
## Purpose
Generating bindings for OpenGL using the [OpenGL registry](https://github.com/KhronosGroup/OpenGL-Registry) is standard boilerplate for many projects. While generating the API bindings is typically trivial, including documentation for said bindings is often less so. Beyond being not required for functionality, the documentation sources are primarily intended for generating a static website in HTML, and less so for code documentation, which makes including it often not worth the extra effort. As someone who likes well-documented code and is an avid enjoyer of inline hints, this tool was created to solve that (admittedly niche) problem.
## How To Use
### Start the Server
```bash
gldoc --api=gl --version=3.3
```
There are few very options for the server, the defaults will likely be suitable for most use-cases.
```
Usage gldoc:
-gles
load documentation for GLES API
-host string
address to serve HTTP requests on (default "localhost")
-port int
port to serve HTTP requests on (default 8888)
-version float
target version for the OpenGL API to document (default 0 for latest/any)
```
### Make Requests
Send GET requests to the server using OpenGL function names as the endpoints, whether it be from a CLI tool, a browser, or HTTP client in a programming language of your choice.
This example simply uses `curl` to make a request for `glBufferData`, then pipes the output to `jq` to unminify and format it for clarity...
```bash
curl --silent localhost:8888/glBufferData | jq
```
### Process Results
...and the resulting reply from above:
```json
{
"name": "glBufferData",
"desc": "creates and initializes a buffer object's data store",
"args": [
{
"name": "target",
"desc": "Specifies the target to which the buffer object is bound for glBufferData, which must be one of the buffer binding targets in the following table:"
},
{
"name": "size",
"desc": "Specifies the size in bytes of the buffer object's new data store."
},
{
"name": "data",
"desc": "Specifies a pointer to data that will be copied into the data store for initialization, or NULL if no data is to be copied."
},
{
"name": "usage",
"desc": "Specifies the expected usage pattern of the data store. The symbolic constant must be GL_STREAM_DRAW, GL_STREAM_READ, GL_STREAM_COPY, GL_STATIC_DRAW, GL_STATIC_READ, GL_STATIC_COPY, GL_DYNAMIC_DRAW, GL_DYNAMIC_READ, or GL_DYNAMIC_COPY."
}
],
"seealso": [
"glBindBuffer",
"glBufferSubData",
"glMapBuffer",
"glUnmapBuffer"
],
"errors": [
"GL_INVALID_ENUM",
"GL_INVALID_VALUE",
"GL_INVALID_OPERATION",
"GL_OUT_OF_MEMORY"
]
}
```
All responses will be structured exactly as above, which is illustrative of the complete DSL. This can be easily read and used to create inline documentation when generating OpenGL bindings, or whatever purpose you may need it for, with very little extra effort.
Note that this is **not** a replacement for the full OpenGL API documentation with detailed notes, examples, or anything else in-depth, which is beyond the scope of this project. It is intended for retreiving only a brief summary of functions and their arguments, typically for generating code-comments, inline documentation, etc.
## Extensions
OpenGL extensions are currently not supported nor planned at this time, though that may be subject to change in the future.