https://github.com/sator-imaging/docfx-pages
Deploy docfx API Reference to GitHub Pages only 1 Action
https://github.com/sator-imaging/docfx-pages
csharp docfx documentation github github-actions github-pages unity unity3d
Last synced: 10 months ago
JSON representation
Deploy docfx API Reference to GitHub Pages only 1 Action
- Host: GitHub
- URL: https://github.com/sator-imaging/docfx-pages
- Owner: sator-imaging
- License: mit
- Created: 2023-12-18T01:06:40.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-03-17T04:08:27.000Z (11 months ago)
- Last Synced: 2025-04-09T23:50:41.333Z (10 months ago)
- Topics: csharp, docfx, documentation, github, github-actions, github-pages, unity, unity3d
- Language: C#
- Homepage: https://sator-imaging.github.io/docfx-pages/
- Size: 775 KB
- Stars: 5
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# `docfx` for GitHub Pages
Deploy beautiful API reference to GitHub Pages with only 1 action. No unnecessary file upload and complicated `docfx` setup.
- ✅ No `.json`, `.yml` and `.csproj` Files Required
- ✅ Automatic HeaderDoc & TOC Generator
- ✅ Unity Project & Editor Extension Supported
| Light Theme | Dark Theme |
|:-----------:|:----------:|
|  | 
## `HeaderDoc` Extraction
`docfx-pages` provides feature to convert block comment at the beginning of source code to Markdown document. Those documents are automatically included into the generated API reference site.
* When project contains only a single script, HeaderDoc won't be extracted.
## Usage
```yaml
- uses: sator-imaging/docfx-pages@v1
id: deployment # required to show url in actions result page.
with:
# required parameters
app_name: 'docfx-pages'
site_title: 'Deploy using sator-imaging/docfx-pages'
site_footer: 'Copyright © HTML Tags'
# optional parameters
class_members: ...
```
### Sample Outputs
- `HeaderDoc` Page
- https://sator-imaging.github.io/docfx-pages/HeaderDocs/Tests/Program.cs.html
- C# Source Code
- https://github.com/sator-imaging/docfx-pages/blob/main/Tests/Program.cs
- Built with `class_members: 'separatePages'` → [Go 🧾](https://sator-imaging.github.io/Unity-AltSourceGenerator/api/index.html)
- Built with `class_members: 'samePage'` → [Go 🧾](https://sator-imaging.github.io/docfx-pages/api/index.html)
- *Note:* this sample demonstrates wrong result when specify `site_logo` or `site_favidon` as full-qualified URL. (Logo image in header is missing. `docfx` supports only relative path.)
## Getting Started
Just enable GitHub Pages in repository setting and paste the code below.
### GitHub Actions Source Code
> [!TIP]
> 👇 Here is boilerplate-included sample code for GitHub Pages by Actions.
```yaml
name: docfx for GitHub Pages
on:
# Runs on pushes targeting the default branch
push:
branches:
- 'main'
##- 'releases/**'
release:
types: [published]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
# Single deploy job since we're just deploying
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
#########################################
###### sator-imaging/docfx-pages ######
#########################################
steps:
# for extensibility, docfx-pages does NOT checkout your repository.
# so you need to checkout manually prior to sator-imaging/docfx-pages.
- name: Checkout
uses: actions/checkout@v4
# after checkout, you can checkout another repo, copy logo image or
# other assets into '.docfx' folder to setup your own docfx environment.
# note that images must be copied into '.docfx/images', 'images' or '.images'.
###### main ######
- uses: sator-imaging/docfx-pages@v1
id: deployment # required to show url in actions result page.
with:
# required options
# NOTE: double-quote (") cannot be used, backquote (`) must be escaped (\`).
app_name: 'Deploy Test'
site_title: 'Deploy Test using sator-imaging/docfx-pages'
site_footer: '× Is HTML accepted?'
# optional
class_members: 'separatePages' # 'separatePages' or 'samePage'
google_analytics: '' # empty to disable
define_symbols: '' # additional preprocessor symbols separated by ';'
# paths must be relative from .docfx folder. default value is used when not set.
# note that url works but only in top page. see sample website for detail.
###site_logo: '.svg'
###site_favicon: '.svg'
# advanced options
# --> https://dotnet.github.io/docfx/docs/template.html?tabs=modern#custom-template
# main.js
# NOTE: double-quote (") cannot be used, backquote (`) must be escaped (\`).
main_js: |
export default {
defaultTheme: 'light',
showLightbox: (img) => true,
iconLinks: [
{
icon: 'github',
href: 'https://github.com/sator-imaging',
title: 'GitHub'
},
],
}
# main.css
# NOTE: double-quote (") cannot be used, backquote (`) must be escaped (\`).
main_css: |
```
## Advanced Usage
Full customize can be done by adding `.docfx` folder to **your repository**.
For example, add logo image to `.docfx/images` folder in your repository.
- `.docfx/images/.svg`
- `.docfx/images/.svg` or `.ico`
then, set options in your GitHub Actions. Note that paths must be relative from `.docfx` folder.
```yaml
- uses: sator-imaging/docfx-pages@v1
with:
site_logo: 'images/.svg'
site_favicon: 'images/.ico'
```
> [!NOTE]
> Default resource folders: `.docfx/images`, `images`, or `.images`
> [!TIP]
> You can prepare `.docfx` contents in your GitHub Actions instead of duplicating/uploading files in repository.
## Builtin Assets
- `images/wikimedia-commons/logo-csharp-recolor.svg`
- C# logo file for `site_logo` and `site_favicon`
- 
- `images/unity/made-with-unity.svg`
- Theme-aware SVG file for `site_logo`
- 
## Technical Notes
- `toc.yml` is automatically generated.
- `README` or `README.md` is generated when doesn't exist.
- `README.md` is used as fallback for `index.md`.
- `LICENSE` or `LICENSE.md` document title is automatically set. (insert `#` at the beginning of first line)
## Devnote
### Tests
Due to GitHub Pages limitation, deploy action must be run on main branch.
Development branch has setted up to invoke main branch action indirectly by updating `test` tag. To do so, run the following command on dev branch to run tests.
- `git pull; git tag -f test; git push --tags -f`
### TODO
- add `docfx_metadata`, `docfx_build` and `docfx_filter` options for easy customization.
- currently, it can be achieved by adding `.docfx` folder and place files correctly.