Skip to content

Commit

Permalink
docs: examples for doc build workflows
Browse files Browse the repository at this point in the history
  • Loading branch information
@spwoodcock
spwoodcock committed Sep 28, 2023
1 parent 244a2a1 commit efd5d40
Show file tree
Hide file tree
Showing 2 changed files with 61 additions and 22 deletions.
49 changes: 44 additions & 5 deletions docs/doxygen_build.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,60 @@

<!-- AUTO-DOC-INPUT:START - Do not remove or modify this section -->

| INPUT | TYPE | REQUIRED | DEFAULT | DESCRIPTION |
|----------------------------------------------------------------|--------|----------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| <a name="input_cache_key"></a>[cache_key](#input_cache_key) | string | false | | The cache key to pass <br>to mkdocs_build, e.g.: echo "cache_key=docs-build-$(date --utc '+%V')" <br>>> $GITHUB_ENV Then use, with: <br>cache_key: ${{ env.cache_key }} |
| <a name="input_output_dir"></a>[output_dir](#input_output_dir) | string | true | | Output directory for Doxygen to <br>compile |
| INPUT | TYPE | REQUIRED | DEFAULT | DESCRIPTION |
| -------------------------------------------------------------- | ------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a name="input_cache_key"></a>[cache_key](#input_cache_key) | string | false | | The cache key to pass <br>to mkdocs_build, e.g.: echo "cache_key=docs-build-$(date --utc '+%V')" <br>>> $GITHUB_ENV Then use, with: <br>cache_key: ${{ env.cache_key }} |
| <a name="input_output_dir"></a>[output_dir](#input_output_dir) | string | true | | Output directory for Doxygen to <br>compile |

<!-- AUTO-DOC-INPUT:END -->

## Outputs

<!-- AUTO-DOC-OUTPUT:START - Do not remove or modify this section -->

No outputs.

<!-- AUTO-DOC-OUTPUT:END -->

## Secrets

<!-- AUTO-DOC-SECRETS:START - Do not remove or modify this section -->

No secrets.
<!-- AUTO-DOC-SECRETS:END -->

<!-- AUTO-DOC-SECRETS:END -->

## Example Usage

```yaml
name: Publish Docs

on:
push:
paths:
- docs/**
- osm_login_python/**
- mkdocs.yml
branches: [main]
# Allow manual trigger (workflow_dispatch)
workflow_dispatch:

jobs:
get_cache_key:
runs-on: ubuntu-latest
steps:
- run: echo "cache_key=docs-build-$(date --utc '+%V')" >> $GITHUB_ENV

build_doxygen:
uses: hotosm/gh-workflows/.github/workflows/doxygen_build.yml@main
with:
output_dir: docs/apidocs
cache_key: ${{ env.cache_key }}

publish_docs:
uses: hotosm/gh-workflows/.github/workflows/mkdocs_build.yml@main
needs: [build_doxygen]
with:
cache_path: docs/apidocs
cache_key: ${{ env.cache_key }}
```
34 changes: 17 additions & 17 deletions docs/mkdocs_build.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@

<!-- AUTO-DOC-INPUT:START - Do not remove or modify this section -->

| INPUT | TYPE | REQUIRED | DEFAULT | DESCRIPTION |
|----------------------------------------------------------------|--------|----------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| <a name="input_cache_key"></a>[cache_key](#input_cache_key) | string | false | | The cache key to receive <br>from a previous job, e.g.: <br>echo "cache_key=docs-build-$(date --utc '+%V')" >> $GITHUB_ENV Then <br>use, with: cache_key: ${{ env.cache_key <br>}} |
| <a name="input_cache_path"></a>[cache_path](#input_cache_path) | string | false | | The path from a previously <br>cached job, e.g. `apidocs` from <br>Doxygen. |
| INPUT | TYPE | REQUIRED | DEFAULT | DESCRIPTION |
| -------------------------------------------------------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a name="input_cache_key"></a>[cache_key](#input_cache_key) | string | false | | The cache key to receive <br>from a previous job, e.g.: <br>echo "cache_key=docs-build-$(date --utc '+%V')" >> $GITHUB_ENV Then <br>use, with: cache_key: ${{ env.cache_key <br>}} |
| <a name="input_cache_path"></a>[cache_path](#input_cache_path) | string | false | | The path from a previously <br>cached job, e.g. `apidocs` from <br>Doxygen. |

<!-- AUTO-DOC-INPUT:END -->

Expand Down Expand Up @@ -43,21 +43,21 @@ on:
workflow_dispatch:

jobs:
# get_cache_key:
# runs-on: ubuntu-latest
# steps:
# - run: echo "cache_key=docs-build-$(date --utc '+%V')" >> $GITHUB_ENV
get_cache_key:
runs-on: ubuntu-latest
steps:
- run: echo "cache_key=docs-build-$(date --utc '+%V')" >> $GITHUB_ENV

# build_doxygen:
# uses: hotosm/gh-workflows/.github/workflows/doxygen_build.yml@main
# with:
# output_dir: docs/apidocs
# cache_key: ${{ env.cache_key }}
build_doxygen:
uses: hotosm/gh-workflows/.github/workflows/doxygen_build.yml@main
with:
output_dir: docs/apidocs
cache_key: ${{ env.cache_key }}

publish_docs:
uses: hotosm/gh-workflows/.github/workflows/mkdocs_build.yml@main
# needs: [build_doxygen]
# with:
# cache_path: docs/apidocs
# cache_key: ${{ env.cache_key }}
needs: [build_doxygen]
with:
cache_path: docs/apidocs
cache_key: ${{ env.cache_key }}
```

0 comments on commit efd5d40

Please sign in to comment.