Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/normanderwan/docfxforunity
DocFX usage example for Unity projects
https://github.com/normanderwan/docfxforunity
docfx gitlab unity unity-documentation unity3d
Last synced: 3 days ago
JSON representation
DocFX usage example for Unity projects
- Host: GitHub
- URL: https://github.com/normanderwan/docfxforunity
- Owner: NormandErwan
- License: mit
- Created: 2017-09-26T01:23:27.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2024-09-03T20:55:55.000Z (4 months ago)
- Last Synced: 2024-12-08T02:08:45.821Z (15 days ago)
- Topics: docfx, gitlab, unity, unity-documentation, unity3d
- Language: C#
- Homepage: https://normanderwan.github.io/DocFxForUnity/
- Size: 14.5 MB
- Stars: 217
- Watchers: 6
- Forks: 31
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# DocFX for Unity
> [DocFX](https://dotnet.github.io/docfx/index.html) usage example for Unity projects
[DocFX](https://dotnet.github.io/docfx/) tool generates a clean documentation that looks like the
[Unity documentation](https://docs.unity3d.com/Manual/index.html) with a manual (written in Markdown) and a scripting
API (from the C# scripts of the project).
This repository contains a simple Unity example project which documentation is automatically generated and deployed
online: . It references both C# API and Unity API.
| DocFxForUnity documentation manual |
|:----------------------------------:|
| [](https://normanderwan.github.io/DocFxForUnity/manual/coniunctis.html) |
| DocFxForUnity documentation scripting API |
|:----------------------------------:|
| [](https://normanderwan.github.io/DocFxForUnity/api/DocFxForUnity.Player.html) |
## Setup your documentation
1. [Install DocFX](https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html#2-use-docfx-as-a-command-line-tool).
2. Copy the `Documentation/` folder to your Unity project:
```diff
.
├── Assets
+ ├── Documentation
├── Package
├── ProjectSettings
└── README.md
```
3. Edit the following properties in `Documentation/docfx.json`, keep the others as it is:
```javascript
{
"build": {
"globalMetadata": // Edit your documentation website info, see: https://dotnet.github.io/docfx/tutorial/docfx.exe_user_manual.html#322-reserved-metadata
{
"_appTitle": "Example Unity documentation",
"_appFooter": "Example Unity documentation",
"_enableSearch": true
},
"sitemap":
{
"baseUrl": "https://normanderwan.github.io/DocFxForUnity" // The URL of your documentation website
}
}
```
It's the configuration file of your documentation.
See for more details.
4. Edit `Documentation/filterConfig.yml`:
```yaml
apiRules:
- include: # The namespaces to generate
uidRegex: ^Your\.Namespace1
type: Namespace
- include:
uidRegex: ^Your\.Namespace2
type: Namespace
- exclude:
uidRegex: .* # Every other namespaces are ignored
type: Namespace
```
It tells DocFX which namespaces you want to generate the documentation.
See for more details.
5. Document your classes and methods. See for more details.
6. (Optional) Add your manual pages:
- Write a Markdown file for each page in `Documentation/manual/`.
- Keep a list of these pages on `Documentation/manual/toc.yml`.
7. (Optional) Add resources such as images:
- Copy them to `Documentation/resources/`.
- Reference them on your docs or manual pages.
- See for more details.
8. (Optional) Document your namespaces:
- For each namespace, add a `Assets/Scripts/Your/Namespace1/Your.Namespace1.md` file:
```yaml
---
uid: Your.Namespace1
summary: Description of the Your.Namespace1 namespace.
---
```
- See to know how it works.
9. Generate your documentation:
- On a command line opened on your project, run:
```bash
cp README.md Documentation/index.md
docfx Documentation/docfx.json --serve
```
- The generated website will be visible at .
If you want to have a more similar look to the Unity documentation, see this UnityFX template for DocFX:
.
## Generate automatically your documentation
If you're using GitHub:
1. Copy the `.github/workflows/documentation.yml` workflow to your Unity project:
```diff
.
+ ├── .github
+ | └── workflows
+ | └── documentation.yml
├── Assets
├── Documentation
├── Package
├── ProjectSettings
└── README.md
```
2. Next push on `main` branch will build and deploy your documentation to `https://.github.io//`!
If you're using GitLab, use the provided
[`.gitlab-ci.yml`](https://github.com/NormandErwan/DocFxForUnity/blob/main/.gitlab-ci.yml).
Generated website is pushed to a `public/` directory. See the
[GitLab Pages documentation](https://docs.gitlab.com/ee/user/project/pages/getting_started_part_four.html) for more
details.
## Troubleshooting / FAQ
- DocFX outputs: `Warning:[ExtractMetadata]No project detected for extracting metadata.`
Solution: On Unity, click [Asset > Open C# Project](https://docs.microsoft.com/fr-fr/visualstudio/cross-platform/media/vstu_open-csharp-project.png?view=vs-2019) to generate the required `.csproj`.
- DocFX outputs: `Warning:[ExtractMetadata]No metadata is generated for Assembly-CSharp,Assembly-CSharp-Editor.`
Solution: Make sure your included your namespace in `Documentation/filterConfig.yml`:
```yaml
- include:
uidRegex: ^Your\.Namespace1
type: Namespace
```
- If you want to reference a specific version of Unity, change this line on your `docfx.json`:
```json
"xref": [ "https://normanderwan.github.io/UnityXrefMaps//xrefmap.yml" ],
```
where `` is a Unity version in the form of `YYYY.x` (*e.g.* 2017.4, 2018.4, 2019.3).
## Disclaimer
This repository is not sponsored by or affiliated with Unity Technologies or its affiliates.
“Unity” is a trademark or registered trademark of Unity Technologies or its affiliates in the U.S. and elsewhere.