search

nicklockwood / Euclid

A Swift library for creating and manipulating 3D geometry
MIT License
644 stars 53 forks source link

[WIP] DocC documentation #77

Closed heckj closed 2 years ago

heckj commented 2 years ago

Work In Progress

Adding DocC documentation to Euclid - a revised PR from the original trial (#75) to explicitly merge into the branch feature/documentation, since part of the changes I'm making constrains the supported version of Swift to version 5.5, specifically to enable DocC processing.

codecov-commenter commented 2 years ago

Codecov Report

Merging #77 (8e39de4) into feature/documentation (26ab3e3) will not change coverage. The diff coverage is 75.00%.

Impacted file tree graph

@@                  Coverage Diff                   @@
##           feature/documentation      #77   +/-   ##
======================================================
  Coverage                  77.61%   77.61%           
======================================================
  Files                         22       22           
  Lines                       4601     4601           
======================================================
  Hits                        3571     3571           
  Misses                      1030     1030
Impacted Files Coverage Δ
Sources/Angle.swift 70.68% <ø> (ø)
Sources/Bounds.swift 81.48% <ø> (ø)
Sources/Color.swift 58.00% <ø> (ø)
Sources/Euclid+AppKit.swift 0.00% <ø> (ø)
Sources/Euclid+CoreGraphics.swift 79.45% <ø> (ø)
Sources/Euclid+CoreText.swift 93.65% <ø> (ø)
Sources/Euclid+SceneKit.swift 61.55% <ø> (ø)
Sources/Line.swift 77.27% <ø> (ø)
Sources/LineSegment.swift 98.57% <ø> (ø)
Sources/Mesh.swift 66.49% <ø> (ø)
... and 12 more

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 26ab3e3...8e39de4. Read the comment docs.

heckj commented 2 years ago

The easiest way to see these specific results is to grab this branch and build it directly with Xcode. Barring that, I'm cobbling up some "how to CLI generate" the content, although the ability to easily generate stand-alone content is only on the "main" branch of swift and DocC that's as yet unreleased... but I suspect that may be the ideal end-goal.

In the meantime, I've exported and zipped a doccarchive bundle from the content above so that you can load it and look through how it's coming together:

(the raw doccarchive bundle is roughly 3.6MB in size)

heckj commented 2 years ago

I'm digging into the various structs and adding lower level documentation, and setting up some organization for that, now.

I've got a script that previews the results on the command line if you want to browse it HTML-wise:

#!/bin/bash

mkdir -p .build/symbol-graphs
swift build --target Euclid -Xswiftc -emit-symbol-graph -Xswiftc -emit-symbol-graph-dir -Xswiftc .build/symbol-graphs
xcrun docc preview Sources/Euclid.docc --fallback-display-name Euclid --fallback-bundle-identifier com.github.nicklockwood.Euclid --fallback-bundle-version 0.1.0 --additional-symbol-graph-dir .build/symbol-graphs

Not checking that in, but wanted to provide it in case it was useful for your own previewing of the branch.

heckj commented 2 years ago

And a side note - with Xcode 13.3 beta out, the capability to generate a docs-archive that's effective for static hosting is now (more easily) possible. I got this working for another repository (one of my projects) if you're curious to see how it looks: https://heckj.github.io/Lindenmayer/documentation/lindenmayer/

If you're so inclined, you could set up the branch "feature/documentation" as a GitHub pages source branch for this repository, and I can add a quick script to generate the content into docs - at which point the Euclid API docs could be pretty quickly hosted on GitHub pages.