From f3dfdf890e240c0aca8219a19139c85929202e2a Mon Sep 17 00:00:00 2001 From: Steven Zeck <8315038+stevenzeck@users.noreply.github.com> Date: Sun, 10 Oct 2021 18:36:30 -0500 Subject: [PATCH 1/3] Use Dokka and Mkdocs to generate documentation --- .github/workflows/update-docs.yml | 42 ++++++++++++++++++++++ .gitignore | 3 ++ build.gradle | 26 ++++++++++++++ docs/readium_colors.css | 6 ++++ mkdocs.yml | 59 +++++++++++++++++++++++++++++++ 5 files changed, 136 insertions(+) create mode 100644 .github/workflows/update-docs.yml create mode 100644 docs/readium_colors.css create mode 100644 mkdocs.yml diff --git a/.github/workflows/update-docs.yml b/.github/workflows/update-docs.yml new file mode 100644 index 0000000000..f3e731a65e --- /dev/null +++ b/.github/workflows/update-docs.yml @@ -0,0 +1,42 @@ +name: Build and deploy MkDocs to GitHub Pages + +on: + push: + branches: + - main + +env: + LATEST_VERSION: 2.1.0 + +jobs: + docs: + runs-on: ubuntu-latest + steps: + - name: Checkout dokka + uses: actions/checkout@v2 + + - name: Set up Python + uses: actions/setup-python@v2 + with: + python-version: 3.6 + + - name: Install Python dependencies + run: | + python -m pip install --upgrade pip + pip install mkdocs mkdocs-material mike + + - uses: actions/setup-java@v2 + with: + java-version: 11 + distribution: 'adopt' + + - name: Run Dokka + run: ./gradlew dokkaGfmMultiModule + + - name: Run MkDocs + run: | + git config --global user.name "${GITHUB_ACTOR}" + git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com" + mike deploy ${{ env.LATEST_VERSION }} + mike set-default ${{ env.LATEST_VERSION }} + mike deploy --rebase --push --update-aliases ${{ env.LATEST_VERSION }} latest diff --git a/.gitignore b/.gitignore index d702614923..0dc6df5fac 100644 --- a/.gitignore +++ b/.gitignore @@ -73,3 +73,6 @@ lint/reports/ # Android Profiling *.hprof + +# Docs +docs/readium diff --git a/build.gradle b/build.gradle index 0c5b00d19c..155e930f3f 100644 --- a/build.gradle +++ b/build.gradle @@ -6,6 +6,7 @@ buildscript { ext.kotlin_version = '1.5.31' + ext.dokka_version = '1.5.30' repositories { google() @@ -18,9 +19,12 @@ buildscript { dependencies { classpath 'com.android.tools.build:gradle:7.0.2' classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version" + classpath "org.jetbrains.dokka:dokka-gradle-plugin:$dokka_version" } } +apply plugin: 'org.jetbrains.dokka' + allprojects { repositories { google() @@ -32,6 +36,28 @@ allprojects { } } +subprojects { project -> + if (project.name == 'test-app' || project.name == 'readium') return + apply plugin: 'org.jetbrains.dokka' + tasks.named("dokkaGfmPartial") { + dokkaSourceSets { + configureEach { + reportUndocumented.set(false) + skipEmptyPackages.set(false) + skipDeprecated.set(true) + } + } + } +} + task clean(type: Delete) { delete rootProject.buildDir } + +task cleanDocs(type: Delete) { + delete "${project.rootDir}/docs/readium", "${project.rootDir}/docs/index.md" +} + +tasks.dokkaGfmMultiModule.configure { + outputDirectory = new File("${project.rootDir}/docs") +} diff --git a/docs/readium_colors.css b/docs/readium_colors.css new file mode 100644 index 0000000000..d4479e8055 --- /dev/null +++ b/docs/readium_colors.css @@ -0,0 +1,6 @@ + body { + --md-primary-fg-color: #449d44; + --md-primary-fg-color--light: #73b02c; + --md-primary-fg-color--dark: #255625; + --md-accent-fg-color: #73b02c; + } diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000000..42eb1b411d --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,59 @@ +site_name: Readium Kotlin + +# Meta tags (placed in header) +site_description: Readium Kotlin is an Android library for rendering books +site_author: Readium Foundation +site_url: https://github.com/readium/kotlin-toolkit + +# Repository (add link to repository on each page) +repo_name: kotlin-toolkit +repo_url: https://github.com/readium/kotlin-toolkit + +# Copyright (shown at the footer) +copyright: 'Copyright © 2021 Readium Foundation' + +# Material theme +theme: + name: 'material' + # favicon: favicon.svg + social: + - type: 'github' + link: 'https://github.com/readium/kotlin-toolkit' + +# Extensions +markdown_extensions: + - admonition + - codehilite: + guess_lang: false + - footnotes + - meta + - def_list + - toc: + permalink: true +# - pymdownx.betterem: +# smart_enable: all +# - pymdownx.caret +# - pymdownx.inlinehilite +# - pymdownx.magiclink +# - pymdownx.smartsymbols +# - pymdownx.superfences + +# Dev server binding +#dev_addr: 127.0.0.1:3001 + +nav: + - Home: migration-guide.md + - API Docs: + - Navigator: readium/navigator/index.md + - Shared: readium/shared/index.md + - Streamer: readium/streamer/index.md + - LCP: readium/lcp/index.md + - OPDS: readium/opds/index.md + +extra_css: + - readium_colors.css + +extra: + version: + provider: mike + From b72d7eec9434d7917ef43c98077a851c010b44d8 Mon Sep 17 00:00:00 2001 From: Steven Zeck <8315038+stevenzeck@users.noreply.github.com> Date: Thu, 14 Oct 2021 20:08:54 -0500 Subject: [PATCH 2/3] Use git to determine Readium version --- .github/workflows/update-docs.yml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.github/workflows/update-docs.yml b/.github/workflows/update-docs.yml index f3e731a65e..f6d922807f 100644 --- a/.github/workflows/update-docs.yml +++ b/.github/workflows/update-docs.yml @@ -5,9 +5,6 @@ on: branches: - main -env: - LATEST_VERSION: 2.1.0 - jobs: docs: runs-on: ubuntu-latest @@ -30,6 +27,9 @@ jobs: java-version: 11 distribution: 'adopt' + - name: Get current Readium version + run: echo "READIUM_VERSION=`git describe --tag --match [0-9]* --abbrev=0`" >> $GITHUB_ENV + - name: Run Dokka run: ./gradlew dokkaGfmMultiModule @@ -37,6 +37,6 @@ jobs: run: | git config --global user.name "${GITHUB_ACTOR}" git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com" - mike deploy ${{ env.LATEST_VERSION }} - mike set-default ${{ env.LATEST_VERSION }} - mike deploy --rebase --push --update-aliases ${{ env.LATEST_VERSION }} latest + mike deploy ${{ env.READIUM_VERSION }} + mike set-default ${{ env.READIUM_VERSION }} + mike deploy --rebase --push --update-aliases ${{ env.READIUM_VERSION }} latest From c2cf2dc6b536bdebcf72d12075819cfbf04baef9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mickae=CC=88l=20Menu?= Date: Fri, 15 Oct 2021 16:28:20 +0200 Subject: [PATCH 3/3] Minor workflow changes --- .github/workflows/update-docs.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/update-docs.yml b/.github/workflows/update-docs.yml index f6d922807f..e8215df1c8 100644 --- a/.github/workflows/update-docs.yml +++ b/.github/workflows/update-docs.yml @@ -1,6 +1,7 @@ -name: Build and deploy MkDocs to GitHub Pages +name: Update documentation on: + workflow_dispatch: push: branches: - main @@ -9,7 +10,7 @@ jobs: docs: runs-on: ubuntu-latest steps: - - name: Checkout dokka + - name: Checkout uses: actions/checkout@v2 - name: Set up Python