Skip to content

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

License

Notifications You must be signed in to change notification settings

CaseyHofland/docfx-unitypackage

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

33 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

DocFX Unity package

logo

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

MIT License Release Release Date

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

Examples

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

About

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

Topics

Resources

License

Stars

Watchers

Forks

Sponsor this project