-
Notifications
You must be signed in to change notification settings - Fork 10
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 #314 from odin-detector/docs
Add Docs
- Loading branch information
Showing
58 changed files
with
2,325 additions
and
2,049 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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
<!DOCTYPE html> | ||
<html> | ||
|
||
<head> | ||
<title>Redirecting to master branch</title> | ||
<meta charset="utf-8"> | ||
<meta http-equiv="refresh" content="0; url=./master/index.html"> | ||
<link rel="canonical" href="master/index.html"> | ||
</head> | ||
|
||
</html> |
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,99 @@ | ||
import json | ||
import logging | ||
from argparse import ArgumentParser | ||
from pathlib import Path | ||
from subprocess import CalledProcessError, check_output | ||
from typing import List, Optional | ||
|
||
|
||
def report_output(stdout: bytes, label: str) -> List[str]: | ||
ret = stdout.decode().strip().split("\n") | ||
print(f"{label}: {ret}") | ||
return ret | ||
|
||
|
||
def get_branch_contents(ref: str) -> List[str]: | ||
"""Get the list of directories in a branch.""" | ||
stdout = check_output(["git", "ls-tree", "-d", "--name-only", ref]) | ||
return report_output(stdout, "Branch contents") | ||
|
||
|
||
def get_sorted_tags_list() -> List[str]: | ||
"""Get a list of sorted tags in descending order from the repository.""" | ||
stdout = check_output(["git", "tag", "-l", "--sort=-v:refname"]) | ||
return report_output(stdout, "Tags list") | ||
|
||
|
||
def get_versions(ref: str, add: Optional[str], remove: Optional[str]) -> List[str]: | ||
"""Generate the file containing the list of all GitHub Pages builds.""" | ||
# Get the directories (i.e. builds) from the GitHub Pages branch | ||
try: | ||
builds = set(get_branch_contents(ref)) | ||
except CalledProcessError: | ||
builds = set() | ||
logging.warning(f"Cannot get {ref} contents") | ||
|
||
# Add and remove from the list of builds | ||
if add: | ||
builds.add(add) | ||
if remove: | ||
assert remove in builds, f"Build '{remove}' not in {sorted(builds)}" | ||
builds.remove(remove) | ||
|
||
# Get a sorted list of tags | ||
tags = get_sorted_tags_list() | ||
|
||
# Make the sorted versions list from main branches and tags | ||
versions: List[str] = [] | ||
for version in ["master", "main"] + tags: | ||
if version in builds: | ||
versions.append(version) | ||
builds.remove(version) | ||
|
||
# Add in anything that is left to the bottom | ||
versions += sorted(builds) | ||
print(f"Sorted versions: {versions}") | ||
return versions | ||
|
||
|
||
def write_json(path: Path, repository: str, versions: str): | ||
org, repo_name = repository.split("/") | ||
struct = [ | ||
dict(version=version, url=f"https://{org}.github.io/{repo_name}/{version}/") | ||
for version in versions | ||
] | ||
text = json.dumps(struct, indent=2) | ||
print(f"JSON switcher:\n{text}") | ||
path.write_text(text) | ||
|
||
|
||
def main(args=None): | ||
parser = ArgumentParser( | ||
description="Make a versions.txt file from gh-pages directories" | ||
) | ||
parser.add_argument( | ||
"--add", | ||
help="Add this directory to the list of existing directories", | ||
) | ||
parser.add_argument( | ||
"--remove", | ||
help="Remove this directory from the list of existing directories", | ||
) | ||
parser.add_argument( | ||
"repository", | ||
help="The GitHub org and repository name: ORG/REPO", | ||
) | ||
parser.add_argument( | ||
"output", | ||
type=Path, | ||
help="Path of write switcher.json to", | ||
) | ||
args = parser.parse_args(args) | ||
|
||
# Write the versions file | ||
versions = get_versions("origin/gh-pages", args.add, args.remove) | ||
write_json(args.output, args.repository, versions) | ||
|
||
|
||
if __name__ == "__main__": | ||
main() |
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,43 @@ | ||
name: Docs CI | ||
on: | ||
push: | ||
pull_request: | ||
|
||
jobs: | ||
docs: | ||
runs-on: ubuntu-latest | ||
steps: | ||
- name: Checkout repository | ||
uses: actions/checkout@v2 | ||
with: | ||
submodules: "true" | ||
|
||
- name: Install Doxygen | ||
run: sudo apt install -y doxygen graphviz | ||
shell: bash | ||
|
||
- name: Generate Doxygen Documentation | ||
run: docs/doxygen.sh | ||
shell: bash | ||
|
||
- name: Build Docs | ||
run: pip install ./python[dev] && sphinx-build -ET docs/ docs/build/html/ | ||
|
||
- name: Sanitize ref name for docs version | ||
run: echo "DOCS_VERSION=${GITHUB_REF_NAME//[^A-Za-z0-9._-]/_}" >> $GITHUB_ENV | ||
|
||
- name: Move to versioned directory | ||
run: mv docs/build/html .github/pages/$DOCS_VERSION | ||
|
||
- name: Write switcher.json | ||
run: python .github/pages/make_switcher.py --add $DOCS_VERSION ${{ github.repository }} .github/pages/switcher.json | ||
|
||
- name: Publish Docs to gh-pages | ||
if: github.event_name == 'push' && github.actor != 'dependabot[bot]' | ||
# We pin to the SHA, not the tag, for security reasons. | ||
# https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions | ||
uses: peaceiris/actions-gh-pages@373f7f263a76c20808c831209c920827a82a2847 # v3.9.3 | ||
with: | ||
github_token: ${{ secrets.GITHUB_TOKEN }} | ||
publish_dir: .github/pages | ||
keep_files: 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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,43 @@ | ||
name: Docs Cleanup CI | ||
|
||
# delete branch documentation when a branch is deleted | ||
# also allow manually deleting a documentation version | ||
on: | ||
delete: | ||
workflow_dispatch: | ||
inputs: | ||
version: | ||
description: "documentation version to DELETE" | ||
required: true | ||
type: string | ||
|
||
jobs: | ||
remove: | ||
if: github.event.ref_type == 'branch' || github.event_name == 'workflow_dispatch' | ||
runs-on: ubuntu-latest | ||
|
||
steps: | ||
- name: Checkout | ||
uses: actions/checkout@v3 | ||
with: | ||
ref: gh-pages | ||
|
||
- name: removing documentation for branch ${{ github.event.ref }} | ||
if: ${{ github.event_name != 'workflow_dispatch' }} | ||
run: echo "REF_NAME=${{ github.event.ref }}" >> $GITHUB_ENV | ||
|
||
- name: manually removing documentation version ${{ github.event.inputs.version }} | ||
if: ${{ github.event_name == 'workflow_dispatch' }} | ||
run: echo "REF_NAME=${{ github.event.inputs.version }}" >> $GITHUB_ENV | ||
|
||
- name: Sanitize ref name for docs version | ||
run: echo "DOCS_VERSION=${REF_NAME//[^A-Za-z0-9._-]/_}" >> $GITHUB_ENV | ||
|
||
- name: update index and push changes | ||
run: | | ||
rm -r $DOCS_VERSION | ||
python make_switcher.py --remove $DOCS_VERSION ${{ github.repository }} switcher.json | ||
git config --global user.name 'GitHub Actions Docs Cleanup CI' | ||
git config --global user.email '[email protected]' | ||
git commit -am "Removing redundant docs version $DOCS_VERSION" | ||
git push |
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 |
---|---|---|
|
@@ -26,3 +26,5 @@ tools/imagej/build/ | |
|
||
tools/python/build/ | ||
tools/python/dist/ | ||
|
||
docs/build/ |
Oops, something went wrong.