Skip to content

feat: add developer documentation as new Antora module#1239

Draft
DeepDiver1975 wants to merge 1 commit intomasterfrom
feat/add-developer-docs-module
Draft

feat: add developer documentation as new Antora module#1239
DeepDiver1975 wants to merge 1 commit intomasterfrom
feat/add-developer-docs-module

Conversation

@DeepDiver1975
Copy link
Copy Markdown
Member

Summary

  • Converts the developer-focused docs from owncloud/ocis (docs/ folder) into a new developer Antora module within this repo
  • Source was Hugo/Markdown; 212 pages converted to AsciiDoc with Hugo shortcodes mapped to AsciiDoc equivalents
  • Navigation defined in modules/developer/partials/nav.adoc and registered in antora.yml

What's included

  • oCIS core: configuration, metrics, migration, backup, release notes/roadmap
  • Development guides: getting started, build, testing, debugging, profiling, tracing, CI, extensions, unit testing
  • Architecture Decision Records: ADR 0001–0028
  • Architecture: upload processing, stat polling, protocol changes, PosixFS, collaborative storage, services communication
  • Flow documentation: login, public upload, request flows
  • Storage: terminology, spaces, namespaces, drivers, backends (CephFS, EOS, DCFS NFS)
  • APIs: HTTP (Graph, WebDAV, TUS upload, authorization) and gRPC
  • CLI commands: creating and documenting service-dependent and service-independent CLIs
  • Clients: rclone (WebDAV sync with basic auth and OIDC)
  • Services (38 services): configuration docs and service-specific guides
  • Releasing guide and deployment (developer-focused examples)
  • 24 images (SVG diagrams and PNGs) preserved under modules/developer/images/

Conversion notes

  • Hugo {{< hint >}} → AsciiDoc admonition blocks ([NOTE], [WARNING], [CAUTION])
  • Hugo {{< figure >}}image:: macros with corrected paths relative to modules/developer/images/
  • Hugo {{< include file="..." >}} referencing auto-generated _includes/ files are marked with // AUTO-GENERATED CONTENT: comments — these would need wiring up separately
  • _index.mdindex.adoc throughout
  • Internal cross-references converted from {{< ref >}} to xref:

Test plan

  • Build locally with npx antora site.yml and verify the developer module renders
  • Check navigation structure in the rendered site
  • Review spot-check pages for conversion quality (headings, links, admonitions, images)
  • Decide whether to wire up the auto-generated service configuration includes

🤖 Generated with Claude Code

Converts the developer-focused docs from owncloud/ocis (docs/ folder)
into a new `developer` Antora module within this repo. Source was
Hugo/Markdown; all 212 pages have been converted to AsciiDoc with
Hugo shortcodes mapped to their AsciiDoc equivalents (hint blocks,
figure macros, cross-references, code fences). Images are preserved
under modules/developer/images/. Navigation is defined in
modules/developer/partials/nav.adoc and registered in antora.yml.

Sections covered: oCIS core, Architecture Decision Records, Flow Docs,
Storage, Development guides, APIs (HTTP/gRPC), CLI Commands, Clients,
Services (38 services), Service-Independent config, Releasing guide.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant