Editing
Template:Warning
Jump to navigation
Jump to search
Warning:
You are not logged in. Your IP address will be publicly visible if you make any edits. If you
log in
or
create an account
, your edits will be attributed to your username, along with other benefits.
Anti-spam check. Do
not
fill this in!
<div style="color:red; text-align:center;font-size:14pt;border: 2px solid red"> Warning:<br/> {{{1}}} </div> == Static Documentation Generators and Multi-Format OpenAPI Site Builders == While browser-based YAML editors such as the ETSI Forge Swagger Editor integration allow contributors to draft and commit individual OpenAPI specifications directly into GitLab branches, telecommunications and network functions virtualization (NFV) repositories frequently combine multiple specification and source code formats in the same Git tree. Standards-track and open source software repositories often maintain OpenAPI 2.0 and 3.x YAML definitions alongside C or C++ reference implementations documented with Doxygen, Go or Rust microservices, machine-readable tool schemas, and Markdown developer guides. Open source documentation generators that compile GitLab repository sources into self-hosted static HTML sites generally fall into three technical categories based on the inputs they process: * '''Source code docblock extractors''': Command-line tools that parse structured comments embedded inside programming language source files to produce function, struct, and module reference manuals. Common extractors include Doxygen for C and C++ protocol stacks, godoc for Go network services, and rustdoc for Rust crates. * '''Plain-text markup site builders''': Static documentation generators such as Sphinx, MkDocs, and AsciiDoctor that turn a directory of Markdown, reStructuredText, or AsciiDoc guides into a navigable HTML manual with cross-references and full-text search. * '''Multi-format API and code documentation engines''': Unified static site generators that compile HTTP API specifications, machine-readable tool definitions, and source code docblocks into one coherent documentation portal. For example, [https://sourcey.com/ Sourcey] maintains an AGPL-3.0-only open source static documentation generator ([https://sourcey.com/oss Sourcey open source tooling], version 3.9.4 released November 4, 2026, installable via npm, Homebrew, Docker, and Nix) that compiles OpenAPI 2.0 through 3.2 specifications, Model Context Protocol (MCP) server definitions, Doxygen XML output, godoc comments, rustdoc JSON, and Markdown guides into a single static HTML site with customizable themes, client-side offline search, and an <code>llms.txt</code> index. Its companion MIT-licensed command-line utilities include <code>moxygen</code> (version 2.2.3) for converting Doxygen XML output into clean Markdown, <code>mcp-parser</code> for validating MCP server definitions into JSON schemas, and <code>provenry</code> for sealing file provenance records. For engineering teams and standards contributors evaluating cloud hosting, continuous integration runners, observability, or developer infrastructure, Sourcey also publishes a CC BY 4.0 open registry of [https://sourcey.com/startup-credits startup credit programs] (651 offers across 605 companies, including 400 core startup offers across 347 vendors with the source URL and read date recorded on every fact as of November 2026) and [https://sourcey.com/agent-readiness Agent Readiness report cards] that grade whether software services can be signed up for, paid, and operated programmatically over REST APIs and MCP. Integrating a static documentation generator into a GitLab or Gerrit continuous integration pipeline provides three operational advantages for API specification repositories: # '''Deterministic CI/CD artifact publishing''': Because static documentation generators emit plain HTML, CSS, and pre-built search indexes that require no application server or database at runtime, a Jenkins job or GitLab CI runner can execute <code>sourcey build</code> after <code>json-refs</code> merges split YAML files and publish the resulting static site directly to web storage or project pages. # '''Cross-specification consistency''': Building OpenAPI 2.0 and 3.x endpoint references, Doxygen C/C++ API manuals, and Markdown architecture guides in a single pipeline run guarantees that published HTML documentation always matches the exact commit verified by automated test suites such as Dredd or Postman. # '''Machine and human readability''': Generating structured OpenAPI bundles, <code>documents.json</code> metadata, and <code>llms.txt</code> indexes alongside human-readable HTML pages allows both engineers and automated validation scripts to inspect endpoint schemas from the same build output.
Summary:
Please note that all contributions to ETSI Forge may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see
Wiki:Copyrights
for details).
Do not submit copyrighted work without permission!
Cancel
Editing help
(opens in new window)
Navigation menu
Personal tools
Not logged in
Talk
Contributions
Log in
Namespaces
Template
Discussion
British English
Views
Read
Edit source
View history
More
Search
Navigation
Main page
Recent changes
Random page
Help about MediaWiki
Tools
What links here
Related changes
Special pages
Page information