Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ire4ever1190/nim-docs-action
Action that builds documentation for a nim project
https://github.com/ire4ever1190/nim-docs-action
Last synced: 11 days ago
JSON representation
Action that builds documentation for a nim project
- Host: GitHub
- URL: https://github.com/ire4ever1190/nim-docs-action
- Owner: ire4ever1190
- License: mit
- Created: 2023-09-26T02:12:12.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2024-09-10T11:06:10.000Z (about 2 months ago)
- Last Synced: 2024-09-10T12:35:58.510Z (about 2 months ago)
- Language: Nim
- Size: 50.8 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
Simple action to build documentation. Deployment needs to be done
separately.
### Features
- [x] Removes `src/` prefix from pages
- [x] Sets commit information for docs
- [x] Checksout the tag so you are building for the latest release (Instead of just the latest development changes)
- [x] Builds indexes first to support `importdoc`
- [x] Can deploy files to Github pages
- [ ] TODO: Build both devel/stable docs
## Setup
### Action
Add this line into your build step somewhere
```yml
- name: "Build documentation"
uses: "ire4ever1190/nim-docs-action@v1"
with:
main-file: src/foo.nim # Replace with your main file
```
Full example to auto deploy to Github pages
```yml
on:
push:
branches:
- master # Replace this with your main branch
workflow_dispatch: # Enable manually rebuilding docs
jobs:
deploy:
permissions:
pages: write # To deploy to Pages
id-token: write # Verify deployment
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: "Setup nim"
uses: jiro4989/setup-nim-action@v2
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
- name: "Build documentation"
uses: ire4ever1190/nim-docs-action@v1
with:
main-file: "src/pantry.nim"
deploy: "pages"
```
### Config
#### Inputs
Only `main-file` is required. Everything else is optional
- `main-file`: Entry point to your library. Builds documentation starting from this (required)
- `out-dir`: Folder to put documentation into
- `project-dir`: Folder containing the .nimble file. Used as working directory for operations
- `build-index`: Whether to build index before building documentation. This is only to support [referencing external symbols](https://nim-lang.org/docs/markdown_rst.html#referencing-markup-external-referencing). If you don't use that then you can turn this off (theindex.html will be built either way)
- `deploy`: Automatically deploy the documentation. Currently only supports 'pages'
#### Outputs
- `site-dir`: Path to directory containing the built documentation
#### Nim
`-d:docgen` is passed when compiling files so you can use that within your config files to conditionally enable docgen flags