CaseyHofland/docfx-unitypackage

DocFX Unity package is a GitHub action for deploying a DocFX website for Unity packages to GitHub Pages.

DocFX Unity package

---

GitHub Action for deploying a DocFX website for Unity packages to Github Pages.
Report Bug · Request Feature

About DocFX Unity package

DocFX Unity package is a GitHub action for deploying a DocFX website for Unity packages to GitHub Pages. These days, Unity maintains a lot of optional packages containing great documentation. This action's goal is to allow you to easily build documentation for Unity packages published on GitHub. It aims to mimic Unity's documentation workflow while keeping the native benefits of DocFX.

Installation

1. In the GitHub of your Unity package, create a branch called "gh-pages".
2. Go to the Settings tab, select "Pages" in the table on the left, then select "Deploy from a Branch" and select "gh-pages" as the branch to deploy from.
3. Go to the Actions tab, select "set up a workflow yourself", then copy and paste the following code:

name: docfx-unitypackage

on:
  workflow_dispatch:
  push:
    branches:
      - main

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: true

      - name: Build
        uses: CaseyHofland/docfx-unitypackage@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_branch: gh-pages
          publish_dir: _site

Every time you push to main, this action will run and your site will get automatically updated with any documentation or API changes.

Prerequisites

Your repository should be a Unity package.

Specifically, the root of your project should contain:

• package.json
• CHANGELOG.md Keep a Changelog
• either LICENSE or LICENSE.md
• either README.md or Documentation~/index.md

Usage

DocFX Unity package has been specifically designed to mimic the affordances and limitations of the Package Manager DocTools@2.1. In theory, you should be able to use the documentation of the version 2.1 tools and everything should work exactly the same, except for the following differences:

• DocFX Unity package is forgiving to beginners. All that is required by the Package Manager DocTools@2.1 is optional, though strongly recommended.
• To add a custom logo and favicon to the generated website, add a file called logo and favicon inside the Documentation~/images/ folder. The recommended logo height is 50px.
• When you don't have a TableOfContents.md in your Documentation~, the manual will be created without a table of contents. This may be preferrable for single-page documentation.
• Unity's per-package metadata, the values you can override in projectMetadata.json, are different from DocFX's per-package metadata.
• Currently, config.json does nothing and preprocessor directives are not generated.

If there are any other changes not listed here, please open an issue to propose it be added to the docs.

Resources

Documentation Guides

• Package documentation guides
• Documenting your package
• Unity Style Guide
• Microsoft Style Guide

Examples

• Unity Clock

Roadmap

High Priority:

• Support preprocessor directives
• Unity API references
• Dependencies API references
• Versioned Documentation

Low Priority:

• Customization options

See the open issues for a full list of proposed features (and known issues).

Contributing

Contributions are always appreciated. You may do so by forking the repo and creating a pull request, or by opening an issue.

1. Fork the Project
2. Create your feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a pull request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Casey Hofland

Formal: hofland.casey@gmail.com

Informal: @CaseyHofland