Publish the generated libosrm C++ API reference at /libosrm-api/ - #46
Open
antheducation wants to merge 1 commit into
Open
Publish the generated libosrm C++ API reference at /libosrm-api/#46antheducation wants to merge 1 commit into
antheducation wants to merge 1 commit into
Conversation
The site's own libosrm page (/docs/<version>/libosrm) has, since 2016, pointed C++ embedders at header files on GitHub instead of offering a reference. This adds the rendered reference to the site so those types are browsable here, and links it from the front page next to DEMO and DOCUMENTATION. libosrm-api/ is generated output pinned to osrm-backend commit e9abd4e0268c692210c4f8e6dcd1d184ff2c8f72 (tip of master, after v26.8.0). Every file except the README is byte-for-byte the output of tools/api-docs/build.py in the backend repo, which runs Doxygen over the public headers and renders the XML with sourcey@3.6.5. Every symbol links back to its exact file and line at that commit. _og/ is intentionally not committed: Jekyll drops leading-underscore paths on GitHub Pages and those files are only social-preview images.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this is
The rendered C++ API reference for
libosrm, published at/libosrm-api/, plus aLIBOSRM C++ API button on the front page next to DEMO and DOCUMENTATION.
Companion PR in the backend repo: Project-OSRM/osrm-backend#7677, which
adds the generator (
tools/api-docs/) and pointsdocs/libosrm.mdand the README here.Why
/docs/<version>/libosrmdocuments the C++ library by linking each type to its header file onGitHub — "a short description of what the types do and where to find documentation on it". The
HTTP and Node.js APIs both have real reference pages here; the C++ one never has. This fills
that gap in the place a reader is already looking.
What is in the diff
libosrm-api/— 64 generated files: a landing page, anapi/index and 56 symbol pages,plus
sourcey.css,sourcey.js, a search index, a sitemap andllms.txt/llms-full.txt.Static HTML, no build step, no runtime dependencies. 421 symbols, 355 links back to the exact header line each was read from at
osrm-backend commit
e9abd4e0268c692210c4f8e6dcd1d184ff2c8f72(tip ofmaster, afterv26.8.0).libosrm-api/README.md— states that the directory is generated and gives the one commandthat regenerates it.
index.html— one added button.Everything except that README is byte-for-byte the output of
python tools/api-docs/build.pyin the backend repo at the pinned commit, so it can beregenerated and diffed rather than trusted.
Two things worth knowing
_og/is deliberately not committed. Sourcey also emits social-preview images under_og/; Jekyll drops leading-underscore paths on GitHub Pages, so they would 404. Excludingthem costs only the
og:imagepreviews and keeps the diff ~3.7 MB smaller. If you wouldrather have them, the fix is an
include: ["_og"]line in a_config.yml, and I will add it.v26.6.1 under
docs/, so committing generated output here follows the existing conventionrather than introducing a new one. I put the reference at the top level rather than under
docs/<version>/because it is pinned to a commit rather than to a release; if you wouldprefer it versioned alongside the VitePress builds, say where and I will move it.
Happy to adjust the button wording, the path, or anything else.