Add DocC to the project and host it where I can read it.

[Richard-Gist]

Is your feature request related to a problem? Please describe.

I like the jazzy docs but I would get so much more from DocC with the articles and nicer layout. Also having those documents available to me locally would be helpful with getting on-boarded.

Describe the solution you'd like

A DocC created for the project or for each framework (whatever makes sense), and a website I can view that DocC.

Describe alternatives you've considered

Keep using Jazzy and the wiki. And then I'll just keep being sad.

[morganzellers]

Sounds like a great addition - Feel free to open a PR for review when you want some review!

[Tyler-Keith-Thompson]

This is a thing: https://github.com/DoccZz/docc2html

[Tyler-Keith-Thompson]

Marking this as low priority since our Jazzy docs just got a really nice upgrade

[nickkaczmarek]

Was looking into this and I think SPM might natively handle static hosting of DocC now

[nickkaczmarek]

@MattFreiburgAsynchrony and I started to delve into this, but aren't yet sure a good tutorial to try this out on. We were starting down the path of trying to make an app that uses the features of SwiftCurrent, but were concerned that we'd be showing mostly how to make a bespoke app and not necessarily showing the features of the lib. Taking a step back to see if providing a use cases directory a la this to see if that might make more sense.

We like the idea of short nuggets that show you what you can do without prescribing an app that does all the things.

All this is to say that we're working on providing something that can instruct new users of how to consume the lib, but not quite sure what the best medium is.

[nickkaczmarek]

^ The project I mentioned takes the approach of having a bunch of use cases in one app. That is not necessarily what I had in mind. What I had in mind was more like a bunch of snippets or perhaps very small apps. Matt might have a different idea, but this is what I was thinking.

[MattFreiburgAsynchrony]

I messed around a fair bit with trying to get a docc-generating GitHub action set up, leaning on the work from the PointFree guys' at Swift Parsing. I got as far as this:

# Build and deploy DocC to GitHub pages. Based off of @karwa's work here:
# https://github.com/karwa/swift-url/blob/main/.github/workflows/docs.yml
name: Documentation

on:
  release:
    types:
      - published
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Package
        uses: actions/checkout@v2
        with:
          fetch-depth: 0

      - name: Download Swift 5.5.1
        run: wget -q https://download.swift.org/swift-5.5.1-release/ubuntu2004/swift-5.5.1-RELEASE/swift-5.5.1-RELEASE-ubuntu20.04.tar.gz
      - name: Extract Swift 5.5.1
        run: tar xzf swift-5.5.1-RELEASE-ubuntu20.04.tar.gz
      - name: Add Swift toolchain to PATH
        run: |
          echo "$GITHUB_WORKSPACE/swift-5.5.1-RELEASE-ubuntu20.04/usr/bin" >> $GITHUB_PATH

      - name: Checkout swift-docc
        uses: actions/checkout@v2
        with:
          repository: apple/swift-docc
          ref: main
          path: swift-docc
      - name: Cache DocC
        id: cache-docc
        uses: actions/cache@v2
        with:
          key: swift-url-docc-build
          path: swift-docc/.build
      - name: Build swift-docc
        if: ${{ !steps.cache-docc.outputs.cache-hit }}
        run: |
          cd swift-docc; swift build --product docc -c release; cd ..

      - name: Checkout swift-docc-render
        uses: actions/checkout@v2
        with:
          repository: apple/swift-docc-render
          ref: main
          path: swift-docc-render
      - name: Build swift-docc-render
        run: |
          cd swift-docc-render; npm install && npm run build; cd ..

      - name: Checkout gh-pages Branch
        uses: actions/checkout@v2
        with:
          ref: gh-pages
          path: docs-out

      - name: Build documentation
        run: >
          rm -rf docs-out/.git;
          rm -rf docs-out/main;

          for tag in $(echo "main");
          do
            echo "⏳ Generating documentation for "$tag" release.";
            
            if [ -d "docs-out/$tag" ] 
            then 
                echo "✅ Documentation for "$tag" already exists.";
            else 
                git checkout "$tag";
                mkdir -p Sources/SwiftCurrent/Documentation.docc;
                export DOCC_HTML_DIR="$(pwd)/swift-docc-render/dist";

                rm -rf .build/symbol-graphs;
                mkdir -p .build/symbol-graphs;
                mkdir -p x86_64-apple-ios15.2-simulator;
                swift build \
                  --target SwiftCurrent \
                  -Xswiftc -emit-symbol-graph \
                  -Xswiftc -emit-symbol-graph-dir \
                  -Xswiftc .build/symbol-graphs \
                  && swift-docc/.build/release/docc convert Sources/SwiftCurrent/Documentation.docc \
                    --fallback-display-name SwiftCurrent \
                    --fallback-bundle-identifier com.wwt.SwiftCurrent \
                    --fallback-bundle-version 0.0.0 \
                    --additional-symbol-graph-dir \
                    .build/symbol-graphs \
                    --transform-for-static-hosting \
                    --hosting-base-path /SwiftCurrent/"$tag" \
                    --output-path docs-out/"$tag" \
                    && echo "✅ Documentation generated for "$tag" release." \
                    || echo "⚠️ Documentation skipped for "$tag".";
            fi;
          done
      
      - name: Fix permissions
        run: 'sudo chown --recursive $USER docs-out'
      - name: Publish documentation to GitHub Pages
        uses: JamesIves/[email protected]
        with:
          branch: gh-pages
          folder: docs-out
          single-commit: true

That gave us Docc documentation for just the SwiftCurrent target hosted in GitHub pages, which is a great first step. However, we had trouble getting the _UIKit and _SwiftUI targets to get docc'd without jumping through some hoops.

When Swift 5.6 and/or Xcode 13.3 get released, I think we'll have more flexibility. I've cobbled together the beginnings of a macOS hosted GitHub action that may get us up and running when they are released. More work will undoubtedly be necessary to get this working. I just couldn't test it until Xcode 13.3 gets released.

name: Documentation

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  build:
    runs-on: macos-latest
    steps:
    - uses: maxim-lobanov/setup-xcode@v1
      with:
        xcode-version: '13.3.0-beta'
        
    - name: Checkout Package
      uses: actions/checkout@v2
      with:
        fetch-depth: 0
        
    - name: Checkout gh-pages Branch
      uses: actions/checkout@v2
      with:
        ref: gh-pages
        path: docs-out
        
    - name: Build documentation
      run: >
        rm -rf docs-out/.git;
        rm -rf docs-out/main;
        
        for target in $(echo "SwiftCurrent"; echo "SwiftCurrent_SwiftUI");
        do
        
          echo "Generating documentation for "$target".";
          git checkout main;

          swift package \
            --allow-writing-to-directory docs-out/main \
            generate-documentation \
            --target "$target" \
            --disable-indexing \
            --transform-for-static-hosting \
            --hosting-base-path SwiftCurrent/main 
            --output-path docs-out/main
        done
        
    - name: Fix permissions
      run: 'sudo chown --recursive $USER docs-out'
      
    - name: Publish documentation to GitHubPages
      uses: JamesIves/[email protected]
      with:
        branch: gh-pages
        folder: docs-out
        single-commit: true

Locally, using the Xcode 13.3-beta3 version, I can run:

xcodebuild docbuild -scheme SwiftCurrent -destination generic/platform=iOS OTHER_DOCC_FLAGS="--transform-for-static-hosting --hosting-base-path SwiftCurrent/main" DOCC_OUTPUT_DIR=./docs

to generate GitHub pages-host able docc documentation. (In order to also document our _SwiftUI target, we'd need to add that to our SwiftCurrent scheme)

Also newly available alongside Swift 5.6 is the DocC swift package plugin, which enables an additional command-line syntax:

swift package --allow-writing-to-directory docs generate-documentation --target SwiftCurrent --disable-indexing --transform-for-static-hosting --hosting-base-path SwiftCurrent/main --output-path docs

Stay tuned...

[nallick]

Xcode 14 to the rescue?

[Tyler-Keith-Thompson]

I wish...we can host it on GitHub pages now but it still can't handle multiple targets. So our docs would be disconnected, but Jazzy is giving us all modules joined.

[Tyler-Keith-Thompson]

Update on this, there's movement/discussion about a real implementation of DocC supporting multiple targets: https://forums.swift.org/t/combined-documentation-of-multiple-targets