-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #191 from brain-bican/preserve_annot
gh pages documentation support added
- Loading branch information
Showing
16 changed files
with
239 additions
and
74 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,33 @@ | ||
# Generating Taxonomy Github Pages | ||
|
||
_This feature is supported on TDT versions >= 1.0.7. Please consider upgrading your project through following the [upgrade guide](Upgrade.md)_ | ||
|
||
The Taxonomy Development Tools (TDT) provides a feature to generate a GitHub Pages site for your taxonomy. This feature allows you to create a user-friendly interface for your taxonomy, making it easier for users to explore and understand the data. | ||
|
||
These pages also works in synergy with the [PURL](https://purl.brain-bican.org/) system, allowing you to create a permanent URL for your taxonomy and cell sets. | ||
|
||
To generate the GitHub Pages for your taxonomy, follow these steps: | ||
|
||
1- In the TDT UI run Actions > Generate > Github Pages | ||
|
||
<p align="center"> | ||
<img src="https://raw.githubusercontent.com/brain-bican/taxonomy-development-tools/main/docs/images/screenshots/docs_menu.png" alt="Documentation generation action." width="300"/> | ||
</p> | ||
|
||
This operation will generate documentation on your project root directory under the `docs` folder and push them to the GitHub. | ||
|
||
2- (This step only needed once, at the first publishing of the GH pages) Navigate to your GitHub repository and go to the `Settings` tab. | ||
|
||
On the left panel select `Pages` and under the `Code and Automation` section. Then select the `gh-pages` branch in the `Branch` section and `Save`. | ||
|
||
<p align="center"> | ||
<img src="https://raw.githubusercontent.com/brain-bican/taxonomy-development-tools/main/docs/images/screenshots/docs_config.png" alt="GH Pages configuration" width="500"/> | ||
</p> | ||
|
||
Then please wait for a few minutes for the GitHub Pages to be generated. In the background a GitHub action is preparing that branch for you. Then your taxonomy will be available at `https://brain-bican.github.io/<your_repository_name>/`. | ||
|
||
## Troubleshooting | ||
|
||
If you cannot see the `gh_pages` branch to select at step 2, you may need to wait a few minutes for the GitHub Pages to be generated. In the background a GitHub action is preparing that branch for you. | ||
|
||
If the branch is still not visible, please navigate to the `Actions` tab in your repository and check the status of the `Publish mkdocs documentation` action. If it is still running, please wait for it to complete (depending on the size of your taxonomy it may take up to 30 minutes). If the action is failed please [report an issue](https://github.com/brain-bican/taxonomy-development-tools/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=) on the TDT repository. Please add the failed steps logs to the issue for the swift resolution. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,34 @@ | ||
name: Publish mkdocs documentation | ||
|
||
on: | ||
workflow_dispatch: | ||
push: | ||
branches: | ||
- main | ||
paths: | ||
- 'docs/**' | ||
|
||
permissions: | ||
contents: write | ||
|
||
jobs: | ||
build-and-publish: | ||
name: Publish mkdocs documentation | ||
runs-on: ubuntu-latest | ||
steps: | ||
- name: Checkout main | ||
uses: actions/checkout@v3 | ||
|
||
- name: Configure Git Credentials | ||
run: | | ||
git config user.name github-actions[bot] | ||
git config user.email 41898282+github-actions[bot]@users.noreply.github.com | ||
- name: Set up Python | ||
uses: actions/setup-python@v4 | ||
with: | ||
python-version: 3.x | ||
|
||
- run: pip install mkdocs-material mkdocs-include-dir-to-nav mkdocs-nav-weight==0.2.0 | ||
|
||
- run: mkdocs gh-deploy --force |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,44 @@ | ||
site_name: $$TAXONOMY_NAME$$ | ||
repo_url: https://github.com/$$PROJECT_GITHUB_ORG$$/$$PROJECT_REPO$$ | ||
repo_name: $$PROJECT_GITHUB_ORG$$/$$PROJECT_REPO$$ | ||
docs_dir: docs | ||
|
||
nav: | ||
- Taxonomy: index.md | ||
- Cell Sets: cell_sets | ||
|
||
theme: | ||
name: material | ||
features: | ||
- navigation.instant | ||
- navigation.tabs | ||
- navigation.tabs.sticky | ||
- navigation.top | ||
- navigation.tracking | ||
- search.highlight | ||
- search.share | ||
- search.suggest | ||
- toc.follow | ||
palette: | ||
# Palette toggle for light mode | ||
- scheme: default | ||
toggle: | ||
icon: material/brightness-7 | ||
name: Switch to dark mode | ||
# Palette toggle for dark mode | ||
- scheme: slate | ||
toggle: | ||
icon: material/brightness-4 | ||
name: Switch to light mode | ||
favicon: assets/logo.webp | ||
logo: assets/logo.webp | ||
|
||
plugins: | ||
- search | ||
- include_dir_to_nav | ||
- mkdocs-nav-weight: | ||
section_renamed: false | ||
index_weight: -10 | ||
warning: true | ||
reverse: false | ||
headless_included: true |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.