Improved Docs Generation

The /docs subfolder on this site is now generated independently from the main repo which means more frequent updates and accuracy in regards to the actual source code.

Since the site is generated with Swift using SwiftySites it made sense to build the site and the DocC documentation in one go. But this requires the entire documentation site to be placed inside the static folder of the statically generated site which is checked under version control.

With the new architecture the DocC script is run independently and its results deployed straight to the docs subfolder leaving the rest of the site unaffected. Similarly when a new blog post is published the documentation stays intact.

The entire automation is orchestrated with GitHub Actions and GitHub Pages. To achieve the subfolder behavior the main site is hosted directly under the GitHub organization while the Docs repository does the heavy lifting of producing the documentation site and deploying it to its own GitHub Page which is automatically linked to the subfolder.

It is not possible for an action running out of the Swift Bitcoin repository to deploy to a different Pages URL. So the trick here is to use a dedicated docs repo and within the workflow checkout a different repository – in this case swift-bitcoin.

…
# Build documentation job
build:
runs-on: ubuntu-latest
steps:
  - name: Checkout
    uses: actions/checkout@v4
    with:
      repository: swift-bitcoin/swift-bitcoin
…

# Deployment job
deploy:
environment:
  name: github-pages
  url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
  - name: Deploy to GitHub Pages
    id: deployment
    uses: actions/deploy-pages@v4

For more details check out the workflow's source. Swift Bitcoin's website and docs is completely open source.

Hopefully this change will lead to better quality documentation.