-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
⬇️ Update kdocs and docusaurus documentation
- Loading branch information
1 parent
de96614
commit ccb0dde
Showing
4 changed files
with
240 additions
and
14 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 |
|---|---|---|
| @@ -1,4 +1,122 @@ | ||
| --- | ||
| sidebar_position: 2 | ||
| sidebar_label: Code Documentation (`Kdocs`) | ||
| --- | ||
| --- | ||
|
|
||
| # Code Documentation (`Kdocs`) | ||
|
|
||
| We use [Dokka](https://kotlinlang.org/docs/dokka/overview.html) to generate Kotlin code documentation for the MTN MOMO API SDK. This ensures that all code added to the repository is accompanied by corresponding documentation, enhancing usability and maintainability. | ||
|
|
||
| The generated documentation is automatically deployed to [https://mtn-momo-sdk.rekast.io/](https://mtn-momo-sdk.rekast.io/) via [GitHub Actions](https://github.com/re-kast/android-mtn-momo-api-sdk/blob/de966147f9a240b2bdf0611663a6fd5b05cf21ae/.github/workflows/docs.yml#L48-L94). This CI/CD pipeline ensures that any updates to the documentation are promptly reflected on the website. | ||
|
|
||
| --- | ||
|
|
||
| ## GitHub Actions Workflow for Dokka | ||
|
|
||
| The following YAML configuration outlines the steps involved in building and deploying the Dokka documentation: | ||
|
|
||
| ```yaml | ||
| build-and-deploy-dokka: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - name: Checkout 🛎️ | ||
| uses: actions/[email protected] | ||
|
|
||
| - name: Set up JDK 17 | ||
| uses: actions/setup-java@v1 | ||
| with: | ||
| java-version: 17 | ||
|
|
||
| - name: Add empty local.properties | ||
| run: | | ||
| touch local.properties | ||
| echo "MOMO_BASE_URL=${MOMO_BASE_URL}" >> local.properties | ||
| echo "MOMO_COLLECTION_PRIMARY_KEY=${MOMO_COLLECTION_PRIMARY_KEY}" >> local.properties | ||
| echo "MOMO_COLLECTION_SECONDARY_KEY=${MOMO_COLLECTION_SECONDARY_KEY}" >> local.properties | ||
| echo "MOMO_REMITTANCE_PRIMARY_KEY=${MOMO_REMITTANCE_PRIMARY_KEY}" >> local.properties | ||
| echo "MOMO_REMITTANCE_SECONDARY_KEY=${MOMO_REMITTANCE_SECONDARY_KEY}" >> local.properties | ||
| echo "MOMO_DISBURSEMENTS_PRIMARY_KEY=${MOMO_DISBURSEMENTS_PRIMARY_KEY}" >> local.properties | ||
| echo "MOMO_DISBURSEMENTS_SECONDARY_KEY=${MOMO_DISBURSEMENTS_SECONDARY_KEY}" >> local.properties | ||
| echo "MOMO_API_USER_ID=${MOMO_API_USER_ID}" >> local.properties | ||
| echo "MOMO_ENVIRONMENT=${MOMO_ENVIRONMENT}" >> local.properties | ||
| echo "MOMO_API_VERSION_V1=${MOMO_API_VERSION_V1}" >> local.properties | ||
| echo "MOMO_API_VERSION_V2=${MOMO_API_VERSION_V2}" >> local.properties | ||
| working-directory: android | ||
|
|
||
| - name: Add empty keystore.properties | ||
| run: touch keystore.properties | ||
| working-directory: android | ||
|
|
||
| - name: Grant execute permission for gradlew | ||
| run: chmod +x gradlew | ||
| working-directory: android | ||
|
|
||
| - name: Document modules with Dokka | ||
| run: ./gradlew dokkaHtmlMultiModule | ||
| working-directory: android | ||
|
|
||
| - name: Deploy 🚀 | ||
| if: ${{ github.event_name == 'push' }} | ||
| uses: JamesIves/[email protected] | ||
| with: | ||
| branch: gh-pages # The branch the action should deploy to. | ||
| folder: android/build/dokka # The folder the action should deploy. | ||
| target-folder: dokka | ||
| ssh-key: ${{ secrets.DEPLOY_KEY }} | ||
| ``` | ||
| ### Explanation of Workflow Steps | ||
| 1. **Checkout the Repository**: The workflow starts by checking out the repository to access the documentation files. | ||
| 2. **Set up JDK 17**: It sets up Java Development Kit (JDK) version 17, which is required for building the documentation. | ||
| 3. **Add Local Properties**: Creates a `local.properties` file with necessary environment variables for the build process. | ||
| 4. **Add Keystore Properties**: Creates an empty `keystore.properties` file, which may be required for signing the application. | ||
| 5. **Grant Execute Permission**: Ensures that the `gradlew` script has execute permissions. | ||
| 6. **Document Modules with Dokka**: Runs the Dokka task to generate HTML documentation for all modules. | ||
| 7. **Deploy to GitHub Pages**: Finally, the generated documentation is deployed to the `gh-pages` branch, making it accessible via the specified URL. | ||
|
|
||
| ## Generating Documentation Locally | ||
|
|
||
| You can also generate documentation locally to preview what will be deployed once the GitHub Actions run. This is made possible by the configuration specified in the `build.gradle.kts` file: | ||
|
|
||
| ```kotlin | ||
| tasks.named<org.jetbrains.dokka.gradle.DokkaMultiModuleTask>("dokkaHtmlMultiModule") { | ||
| moduleName.set("| MTN MOMO ANDROID SDK") | ||
| moduleVersion.set(project.version.toString()) | ||
| outputDirectory.set(layout.buildDirectory.dir("dokka")) | ||
| pluginConfiguration<DokkaBase, DokkaBaseConfiguration> { | ||
| customAssets = listOf(layout.projectDirectory.file("assets/logo-icon.svg").asFile) | ||
| customStyleSheets = listOf((layout.projectDirectory.file("assets/rekast.css").asFile)) | ||
| footerMessage = "© Re.Kast Limited" | ||
| separateInheritedMembers = false | ||
| } | ||
| pluginsMapConfiguration.set( | ||
| mapOf( | ||
| "org.jetbrains.dokka.base.DokkaBase" to """{ "separateInheritedMembers": false }""" | ||
| ) | ||
| ) | ||
| } | ||
| ``` | ||
|
|
||
| ### Steps to Generate Documentation Locally | ||
|
|
||
| 1. Navigate to the `android` folder in your project directory: | ||
| ```bash | ||
| cd android | ||
| ``` | ||
| 2. Run the following command to generate the documentation: | ||
| ```bash | ||
| ./gradlew dokkaHtmlMultiModule | ||
| ``` | ||
| 3. Check the root `build` folder for a folder named `dokka`. | ||
| 4. Open the `index.html` file generated in the `dokka` folder to preview the documentation. | ||
|
|
||
| ## Additional Resources | ||
|
|
||
| - **Dokka Documentation**: For more information on how to use Dokka, refer to the [official documentation](https://kotlinlang.org/docs/dokka/overview.html). | ||
| - **Kotlin Documentation**: Learn more about Kotlin and its features by visiting the [Kotlin documentation](https://kotlinlang.org/docs/home.html). | ||
| - **GitHub Actions Documentation**: For details on automating workflows with GitHub Actions, check out the [GitHub Actions documentation](https://docs.github.com/en/actions). | ||
|
|
||
| By following this documentation, developers can effectively generate and maintain code documentation for the MTN MOMO API SDK, ensuring that it remains accessible and useful for all users. |
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 |
|---|---|---|
| @@ -1,4 +1,87 @@ | ||
| --- | ||
| sidebar_position: 1 | ||
| sidebar_label: Library Usage | ||
| --- | ||
| --- | ||
|
|
||
| # Library Usage | ||
|
|
||
| The MTN MOMO API SDK documentation is built using [Docusaurus](https://docusaurus.io/), a modern static website generator that simplifies the creation of documentation websites. The documentation files are organized in a structured manner within the [versioned_docs folder](https://github.com/re-kast/android-mtn-momo-api-sdk/tree/feature/issue_27/versioned_docs), with the current version being `1.0`. You can find all relevant documentation in the `version-1.0` folder. | ||
|
|
||
| --- | ||
|
|
||
| ## Deployment | ||
|
|
||
| The documentation is automatically deployed to [https://mtn-momo-sdk.rekast.io/](https://mtn-momo-sdk.rekast.io/) using [GitHub Actions](https://github.com/re-kast/android-mtn-momo-api-sdk/blob/de966147f9a240b2bdf0611663a6fd5b05cf21ae/.github/workflows/docs.yml#L20-L46). This CI/CD pipeline ensures that any updates to the documentation are promptly reflected on the website, providing users with the latest information. | ||
|
|
||
| ### GitHub Actions Workflow | ||
|
|
||
| The following YAML configuration outlines the steps involved in building and deploying the Docusaurus documentation: | ||
|
|
||
| ```yaml | ||
| build-and-deploy-docusaurus: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - uses: actions/[email protected] | ||
| - uses: actions/setup-node@v3 | ||
| with: | ||
| node-version: 18 | ||
| cache: yarn | ||
|
|
||
| - name: Install dependencies | ||
| run: yarn install | ||
|
|
||
| - name: Build website | ||
| run: yarn build | ||
|
|
||
| - name: Copy docs into build working-directory | ||
| run: | | ||
| cp -r docs ./build | ||
| cp -r CNAME ./build | ||
| - name: Deploy to gh-pages | ||
| if: ${{ github.event_name == 'push' }} | ||
| uses: peaceiris/actions-gh-pages@v3 | ||
| with: | ||
| github_token: ${{ secrets.GITHUB_TOKEN }} | ||
| publish_branch: gh-pages | ||
| publish_dir: ./build | ||
| user_name: github-actions[bot] | ||
| user_email: 41898282+github-actions[bot]@users.noreply.github.com | ||
| ``` | ||
| ### Explanation of Workflow Steps | ||
| 1. **Checkout the Repository**: The workflow starts by checking out the repository to access the documentation files. | ||
| 2. **Setup Node.js**: It sets up Node.js version 18, which is required for building the Docusaurus site. | ||
| 3. **Install Dependencies**: The workflow installs the necessary dependencies using Yarn, ensuring that all required packages are available for the build process. | ||
| 4. **Build the Website**: It builds the Docusaurus site, generating static files for deployment. | ||
| 5. **Copy Documentation**: The documentation files and CNAME (for custom domains) are copied into the build directory to ensure they are included in the deployment. | ||
| 6. **Deploy to GitHub Pages**: Finally, the built files are deployed to the `gh-pages` branch, making them accessible via the specified URL. | ||
|
|
||
| ## Running Documentation Locally | ||
|
|
||
| To preview the documentation locally before deployment, follow these steps: | ||
|
|
||
| 1. Ensure you have Node.js and Yarn installed on your machine. | ||
| 2. Navigate to the root project folder: | ||
| ```bash | ||
| cd path/to/your/project | ||
| ``` | ||
| 3. Run the following command to build the documentation site: | ||
| ```bash | ||
| yarn build | ||
| ``` | ||
| 4. Start a local server to serve the site: | ||
| ```bash | ||
| npm run serve | ||
| ``` | ||
| 5. Open your web browser and navigate to `http://localhost:3000` to view the documentation. | ||
|
|
||
| ## Additional Resources | ||
|
|
||
| - **Docusaurus Documentation**: For more information on how to use Docusaurus, refer to the [official documentation](https://docusaurus.io/docs). | ||
| - **GitHub Actions Documentation**: Learn more about GitHub Actions and how to automate your workflows by visiting the [GitHub Actions documentation](https://docs.github.com/en/actions). | ||
| - **Node.js Documentation**: For details on Node.js and its features, check out the [Node.js documentation](https://nodejs.org/en/docs/). | ||
| - **Yarn Documentation**: For more information on using Yarn as a package manager, visit the [Yarn documentation](https://classic.yarnpkg.com/en/docs/). | ||
|
|
||
| By following this documentation, developers can effectively utilize the MTN MOMO API SDK and contribute to its ongoing development and documentation efforts. This ensures that the SDK remains accessible, well-documented, and easy to integrate into applications. |
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