diff --git a/.github/workflows/docs_ci.yaml b/.github/workflows/docs_ci.yaml new file mode 100644 index 0000000..376a8d6 --- /dev/null +++ b/.github/workflows/docs_ci.yaml @@ -0,0 +1,32 @@ +# This is a basic workflow to help you get started with Actions + +name: MKDocs + +# Controls when the action will run. Triggers the workflow on push or pull request +# events but only for the main branch +on: + push: + branches: [main] + +# A workflow run is made up of one or more jobs that can run sequentially or in parallel +jobs: + # This workflow contains a single job called "build" + build: + # The type of runner that the job will run on + runs-on: ubuntu-latest + + permissions: + contents: write + packages: write + attestations: write + id-token: write + + # Steps represent a sequence of tasks that will be executed as part of the job + steps: + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it + - uses: actions/checkout@v4 + with: + fetch-depth: '0' + - uses: tercen/actions/mkdocs@main + with: + committers_api_key: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file diff --git a/.github/workflows/docs_release.yaml b/.github/workflows/docs_release.yaml new file mode 100644 index 0000000..9cdc790 --- /dev/null +++ b/.github/workflows/docs_release.yaml @@ -0,0 +1,34 @@ +# This is a basic workflow to help you get started with Actions + +name: MKDocs release + +# Controls when the action will run. Triggers the workflow on push or pull request +# events but only for the main branch +on: + push: + tags: + - '[0-9]+.[0-9]+.[0-9]+' + +# A workflow run is made up of one or more jobs that can run sequentially or in parallel +jobs: + # This workflow contains a single job called "build" + build: + # The type of runner that the job will run on + runs-on: ubuntu-latest + permissions: + contents: write + packages: write + attestations: write + id-token: write + + # Steps represent a sequence of tasks that will be executed as part of the job + steps: + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it + - uses: actions/checkout@v4 + with: + fetch-depth: '0' + - uses: tercen/actions/mkdocs@main + with: + set_default: "true" + tag: ${GITHUB_REF##*/} + committers_api_key: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..33ddd88 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +site/ +.idea +.vscode \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..dfd9fc8 --- /dev/null +++ b/README.md @@ -0,0 +1,89 @@ +# Instructions for using Template + +## Manual Tasks After Using Template + +Manual changes to be made to the new repository. + +### 1. Create branch on GitHub + +![image](https://github.com/user-attachments/assets/0d436459-20c8-4057-8bdb-9e8b5a28fc35) + +### 2. Create Initial Tag + +Revision structure is based on the related software major revision number. + +e.g . If the document relates to Tercen and Tercen is at revision 0.15.5 then the document is 0.15.x + +The Minor revision is the document revision. + +### 3. Changes to mkdocs.yaml + +Change the following to what is relevant to the new repository. Replace the "administrators_guide" below references. + +``` +site_name: Tercen Administrators Guide +repo_url: https://github.com/tercen/administrators_guide +repo_name: tercen/administrators_guide +repository: tercen/administrators_guide +``` + +## Markdown Examples + +Bolded List + +- **Yellow:** Factor names for id codes and experimental data. +- **Green:** Factor names for measurements. +- **Blue, Beige, Orange:** Individual records with data. + +Quote feature for drag and drop function + +_**From Gather**_ +> Value to Y-Axis. +> Variable to Row. + +Table + +| Name | Good looking score | Text | +| --------------------- | ------------------ | ------- | +| Tommy | 7 | | +| Hansel from Zoolander | 933 | | +| You | 10 | ASFSADF | + +## Navigation Table in mkdocs.yaml + +When finished creating the individual Markdown pages to a tutorial they have to me referenced in the mkdocs.yaml file. + +The top level of the hierarchy (Introduction & Tutorial) is displayed in tabs in the MKDocs deployment. +Subsequent indents become the right sidebar navigation of a Tab. +An In-page navigation is generated in the left sidebar from the markdown headings in the document. + +```nav: + - Introduction: index.md + - Tutorial: + - Create a Project: create_a_project.md + - Upload Data: upload_data.md + - Basic Analysis - Workflow: workflow.md + - Using Operators: operators.md + - Join Data files: join.md + - Export a Data Table: export_data.md + - Perform a Gather: gather.md + - Apply a Filter: filter.md + - Collaboration Tips: collaborate.md +``` + +## Local Build Instructions (Linux) + +```shell +docker run --rm -it \ + -p 8000:8000 \ + -v ${PWD}:/docs \ + -e MKDOCS_GIT_COMMITTERS_APIKEY=$GITHUB_TOKEN \ + --entrypoint sh \ + squidfunk/mkdocs-material + +pip install mike +pip install mkdocs-git-committers-plugin-2 +pip install mkdocs-git-revision-date-localized-plugin + +mkdocs serve --dev-addr=0.0.0.0:8000 +``` diff --git a/docs/images/tercen-logo-sq.svg b/docs/images/tercen-logo-sq.svg new file mode 100644 index 0000000..0b3370c --- /dev/null +++ b/docs/images/tercen-logo-sq.svg @@ -0,0 +1,25 @@ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..2bbca1d --- /dev/null +++ b/docs/index.md @@ -0,0 +1,2 @@ +# Home + diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..d12b6b8 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,140 @@ +site_name: Tercen Starter Guide +docs_dir: docs/ +site_url: https://tercen.com +repo_url: https://github.com/tercen/mkdoc_playground +repo_name: tercen/starter_guide +edit_uri: edit/main/docs/ +site_author: "Tercen Authors" +site_description: "Documentation template" +use_directory_urls: true + +copyright: Copyright © 2024 Tercen + +theme: + name: material + # custom_dir: .docs/overrides/ + font: false + favicon: https://tercen.com/_assets/brand/fav.png + logo: ./images/tercen-logo-sq.svg + icon: + repo: fontawesome/brands/github + features: + - content.tabs.link + - instant + - navigation.footer + - navigation.path + - navigation.sections + # - navigation.expand + - navigation.tabs + # - navigation.tabs.sticky + - navigation.top + - navigation.tracking + - search.highlight + - search.share + - search.suggest + - tabs + - content.code.annotate + - content.code.copy + - content.action.edit + - content.action.view +extra_css: + - stylesheets/style.css +plugins: + - search + - git-committers: + repository: tercen/mkdoc_playground + branch: main + - git-revision-date-localized: + enable_creation_date: true + type: timeago + # - exclude: + # glob: + # - README.md + # - "*.gotmpl" + # - "*.gotmpl.md" + # - awesome-pages + # - macros: + # module_name: .docs/macros/includes/main + - minify: + minify_html: true + minify_js: true + htmlmin_opts: + remove_comments: true + #js_files: [] + # - redirects: + # redirect_maps: + # README.md: Getting-Started/intro.md + - mike: + # these fields are all optional; the defaults are as below... + version_selector: true # set to false to leave out the version selector + css_dir: css # the directory to put the version selector's CSS + javascript_dir: js # the directory to put the version selector's JS + canonical_version: + null # the version for ; `null` + # uses the version specified via `mike deploy` +markdown_extensions: + - admonition + - attr_list + - def_list + - footnotes + - meta + - toc: + permalink: true + - tables + - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - pymdownx.highlight: + anchor_linenums: true + use_pygments: true + linenums: true + - pymdownx.inlinehilite + - pymdownx.keys + - pymdownx.magiclink + - pymdownx.mark + - pymdownx.snippets + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.superfences + - pymdownx.tabbed +extra: + version: + provider: mike + +#nav: +# - Home: index.md +# - Getting started: +# - Guidelines: intro_guidelines.md +# - Getting started: +# - Core concepts: getting-started_core-concepts.md +# - Setting up Tercen Studio: getting-started_setup-tercen-studio.md +# - R Operator development: +# - General workflow: operator-dev_intro.md +# - "Walkthrough example: R operator": operator-dev_create.md +# - Deploying an R operator: operator-dev_deploy.md +# - Improving an operator: operator-dev_improve.md +# - Python Operator development: +# - Getting familiar with Tercen Studio: operator-dev_python.md +# - Advanced concepts: +# - Continuous Integration Workflow: operator-dev_ci.md +# - Installing an Operator: operator-dev_installation.md +# - Common patterns: operator-dev_patterns.md +# - Templates: +# - Building a template: templates-apps_templates.md +# - Apps: +# - Building an app: templates-apps_apps.md +# - Library: +# - Tercen Library: library.md +# - Best practices: +# - Development guidelines: best-practices_guidelines.md +# - Using tim: best-practices_using-tim.md +# - Troubleshooting: +# - Common operator issues: troubleshooting_common-issues.md +# - CI and Github Actions: troubleshooting_ci.md +# - Going forward: +# - Next steps: going-forward_next-steps.md +# - Appendix: +# - Glossary: appendix_glossary.md +# - Organisation setup: appendix_organisation-setup.md +# - Tercen Studio: appendix_tercen-studio.md