diff --git a/.github/workflows/antora.yml b/.github/workflows/antora.yml deleted file mode 100644 index 133af868..00000000 --- a/.github/workflows/antora.yml +++ /dev/null @@ -1,43 +0,0 @@ -name: Generate MicroProfile Tutorial - -on: - push: - branches: - - main # Or your default branch - -jobs: - build-and-deploy: - runs-on: ubuntu-latest - permissions: - id-token: write # Required for authentication - contents: read # Required to read repository contents - pages: write # Required to deploy to GitHub Pages - steps: - - name: Checkout Repository - uses: actions/checkout@v3 - - - name: Set up Node.js - uses: actions/setup-node@v3 - with: - node-version: '18' # Use a compatible Node.js version - - - name: Install Antora Locally - run: npm install @antora/cli @antora/site-generator-default - - - name: Verify Antora Installation - run: npm list @antora/cli @antora/site-generator-default || echo "Antora packages are not installed." - - - name: Generate Site with Antora - run: npx antora --fetch --stacktrace playbook.yml - - - name: Setup Pages - uses: actions/configure-pages@v4 - - - name: Upload Antora Site to GitHub Pages - uses: actions/upload-pages-artifact@v3 - with: - path: ./build/site # The output directory for Antora - - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 \ No newline at end of file diff --git a/.github/workflows/build-and-deploy-tutorial.yml b/.github/workflows/build-and-deploy-tutorial.yml index 93a530e5..9e80a9ea 100644 --- a/.github/workflows/build-and-deploy-tutorial.yml +++ b/.github/workflows/build-and-deploy-tutorial.yml @@ -61,6 +61,13 @@ jobs: npm install @antora/cli @antora/site-generator-default npm install @antora/lunr-extension @antora/pdf-extension @asciidoctor/tabs gem install asciidoctor-pdf asciidoctor-kroki asciidoctor-plantuml + + # Make update-repo-url.sh executable and run it to update URLs + - name: Make update-repo-url.sh executable + run: chmod +x ./update-repo-url.sh + + - name: Update repository URLs in configuration files + run: ./update-repo-url.sh # Generate the documentation site to validate it builds correctly - name: Validate Site Generation diff --git a/.github/workflows/pages-antora.yml b/.github/workflows/pages-antora.yml deleted file mode 100644 index a5e82967..00000000 --- a/.github/workflows/pages-antora.yml +++ /dev/null @@ -1,43 +0,0 @@ -name: Generate MicroProfile Tutorial - -on: - push: - branches: - - main # Or your default branch - -jobs: - build-and-deploy: - runs-on: ubuntu-latest - permissions: - id-token: write # Required for authentication - contents: read # Required to read repository contents - pages: write # Required to deploy to GitHub Pages - steps: - - name: Checkout Repository - uses: actions/checkout@v3 - - - name: Set up Node.js - uses: actions/setup-node@v3 - with: - node-version: '18' # Use a compatible Node.js version - - - name: Install Antora Locally - run: npm install @antora/cli @antora/site-generator-default - - - name: Verify Antora Installation - run: npm list @antora/cli @antora/site-generator-default || echo "Antora packages are not installed." - - - name: Generate Site with Antora - run: npx antora --fetch --stacktrace playbook.yml - - - name: Setup Pages - uses: actions/configure-pages@v4 - - - name: Upload Antora Site to GitHub Pages - uses: actions/upload-pages-artifact@v3 - with: - path: ./build/site # The output directory for Antora - - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 diff --git a/.github/workflows/pages-static.yml b/.github/workflows/pages-static.yml deleted file mode 100644 index f2c9e97c..00000000 --- a/.github/workflows/pages-static.yml +++ /dev/null @@ -1,43 +0,0 @@ -# Simple workflow for deploying static content to GitHub Pages -name: Deploy static content to Pages - -on: - # Runs on pushes targeting the default branch - push: - branches: ["main"] - - # Allows you to run this workflow manually from the Actions tab - workflow_dispatch: - -# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages -permissions: - contents: read - pages: write - id-token: write - -# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. -# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. -concurrency: - group: "pages" - cancel-in-progress: false - -jobs: - # Single deploy job since we're just deploying - deploy: - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - - name: Setup Pages - uses: actions/configure-pages@v5 - - name: Upload artifact - uses: actions/upload-pages-artifact@v3 - with: - # Upload entire repository - path: '.' - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 diff --git a/.github/workflows/static.yml b/.github/workflows/static.yml deleted file mode 100644 index f2c9e97c..00000000 --- a/.github/workflows/static.yml +++ /dev/null @@ -1,43 +0,0 @@ -# Simple workflow for deploying static content to GitHub Pages -name: Deploy static content to Pages - -on: - # Runs on pushes targeting the default branch - push: - branches: ["main"] - - # Allows you to run this workflow manually from the Actions tab - workflow_dispatch: - -# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages -permissions: - contents: read - pages: write - id-token: write - -# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. -# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. -concurrency: - group: "pages" - cancel-in-progress: false - -jobs: - # Single deploy job since we're just deploying - deploy: - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - - name: Setup Pages - uses: actions/configure-pages@v5 - - name: Upload artifact - uses: actions/upload-pages-artifact@v3 - with: - # Upload entire repository - path: '.' - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 329afec1..44c21549 100644 --- a/.gitignore +++ b/.gitignore @@ -70,4 +70,7 @@ wlp/usr/servers/*/configDropins/ liberty-rest-app/target/ mp-ecomm-store/target/ -/node_modules/ \ No newline at end of file +/node_modules/ + +# Antora build output +/build/ \ No newline at end of file diff --git a/README.adoc b/README.adoc index d16aa5f0..6b21f30e 100644 --- a/README.adoc +++ b/README.adoc @@ -4,7 +4,7 @@ :toclevels: 3 :doctype: book -The MicroProfile Tutorial is a comprehensive guide for learning about Eclipse MicroProfile. This repository contains the documentation built with Antora. +The MicroProfile Tutorial is a comprehensive guide for learning about https://microprofile.io[MicroProfile]. This repository contains the documentation built with https://antora.org/[Antora]. toc::[] @@ -15,7 +15,7 @@ This repository contains the documentation for the MicroProfile Tutorial, built ## Prerequisites ### Install Antora -You need to install Antora using npm. If you don't have npm installed, you can install it by following the instructions at https://docs.npmjs.com/getting-started/installing-node. +You need to https://docs.antora.org/antora/latest/install-and-run-quickstart/#install-antora[install Antora] using npm. If you don't have Node.js installed, you can https://docs.antora.org/antora/latest/install-and-run-quickstart/#install-nodejs[install Node.js] by following this instructions. ``` npm install -g @antora/cli @antora/site-generator-default @@ -38,7 +38,9 @@ antora antora-assembler.yml ./fix-edit-links.sh ``` -The first command ensures that the repository URLs are up-to-date. The second command will generate the site in the `build/site` directory. The third command fixes the "Edit this Page" links to properly point to GitHub instead of local file paths. +- The first command ensures that the repository URLs are up-to-date. +- The second command will generate the site in the `build/site` directory. +- The third command fixes the "Edit this Page" links to properly point to GitHub instead of local file paths. Alternatively, you can use the following one-liner: @@ -46,8 +48,6 @@ Alternatively, you can use the following one-liner: ./update-repo-url.sh && antora antora-assembler.yml && ./fix-edit-links.sh ``` -After building, you can open the `build/site/index.html` file in your web browser to view the site. - ## Running the Site Locally You can run the site locally using Python's built-in HTTP server. First, navigate to the `build/site` directory: @@ -189,6 +189,7 @@ start_page: index.adoc ---- Key properties: + - **name**: The component name used in xrefs and URLs - **title**: The human-readable title - **version**: The component version (appears in URLs and version selector) @@ -241,6 +242,7 @@ The main navigation structure is defined in `modules/ROOT/pages/nav.adoc`: ---- Navigation entries can be: + - Direct links to pages (with `xref:`) - Unlinked category headers (without `xref:`) - Nested to create hierarchical structures (using multiple `*` characters) @@ -383,7 +385,6 @@ The MicroProfile Tutorial follows the standard Antora directory structure: - `modules/ROOT/pages/` - Contains the main documentation content in AsciiDoc format - `modules/ROOT/assets/images/` - Contains images used in the documentation -- `modules/ROOT/examples/` - Contains code examples (if applicable) ### AsciiDoc Best Practices @@ -449,7 +450,6 @@ If you encounter issues not covered in this documentation, check the following r - [Antora Documentation](https://docs.antora.org/) - [AsciiDoc Syntax Quick Reference](https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/) -- [MicroProfile Community](https://microprofile.io/community/) ## Hosting and Deployment @@ -529,6 +529,153 @@ If you're hosting the documentation on a custom domain: 2. Configure your domain's DNS settings to point to your hosting provider 3. If using GitHub Pages, add a CNAME file to the `build/site` directory +## GitHub Actions Workflow for Automated Deployment + +The MicroProfile Tutorial documentation is automatically built and deployed using a GitHub Actions workflow. This section explains the workflow configuration and how it ensures continuous deployment of the documentation. + +### Workflow Overview + +The repository includes a comprehensive GitHub Actions workflow (`antora.yml`) that: + +- **Validates builds on pull requests** without deploying +- **Automatically deploys** to GitHub Pages when changes are pushed to the main branch +- **Handles concurrent deployments** to prevent conflicts +- **Ensures GitHub Pages is enabled** automatically + +### Workflow Configuration + +The workflow is defined in `.github/workflows/build-and-deploy-tutorials.yml` and includes two main jobs: + +#### 1. Pull Request Validation (`validate-build`) + +This job runs on pull requests and validates that the documentation builds correctly: + +- **Triggers**: Pull requests to the main branch +- **Purpose**: Validates documentation builds without deploying +- **Steps**: + * Checkout repository code + * Set up Node.js environment with npm caching + * Install Antora CLI and site generator + * Generate the site to validate build success + * Verify build output exists + +#### 2. Build and Deploy (`build-and-deploy`) + +This job runs on pushes to the main branch and deploys the documentation: + +- **Triggers**: Pushes to main branch, manual workflow dispatch +- **Purpose**: Build and deploy documentation to GitHub Pages +- **Environment**: Uses `github-pages` environment for deployment tracking +- **Steps**: + * Checkout repository code + * Set up Node.js environment with npm caching + * Install Antora CLI and site generator + * Verify Antora installation + * Generate site using Antora with `--fetch` and `--stacktrace` options + * Configure GitHub Pages settings + * Upload generated site as artifact + * Deploy to GitHub Pages + +### Key Features + +#### Concurrency Control +```yaml +concurrency: + group: "pages" + cancel-in-progress: false +``` +Prevents multiple deployments from running simultaneously while allowing in-progress deployments to complete. + +#### Automatic Pages Enablement +The workflow automatically enables GitHub Pages if it's not already configured, ensuring the repository is properly set up for deployment. + +#### Environment Protection +Uses the `github-pages` environment for deployment tracking and provides the deployment URL after successful completion. + +#### Performance Optimizations +- **npm caching**: Speeds up Node.js setup +- **Conditional deployment**: Only deploys from main branch pushes +- **Comprehensive error handling**: Includes verification steps and detailed logging + +### Required Permissions + +The workflow requires specific GitHub token permissions: + +```yaml +permissions: + id-token: write # Required for OIDC authentication to GitHub Pages + contents: read # Required to read repository contents and checkout code + pages: write # Required to deploy artifacts to GitHub Pages +``` + +### Deployment Process + +When code is pushed to the main branch: + +1. **Build Validation**: The workflow validates that Antora can successfully build the site +2. **Site Generation**: Antora processes the `antora-assembler.yml` configuration and generates the static site +3. **Pages Configuration**: GitHub Pages is automatically configured if needed +4. **Artifact Upload**: The generated site (`./build/site`) is uploaded as a deployment artifact +5. **Deployment**: The artifact is deployed to GitHub Pages + +### Accessing the Deployed Site + +After successful deployment, the documentation is available at: +``` +https://.github.io// +``` + +For the MicroProfile Tutorial, this would be: +``` +https://microprofile.github.io/microprofile-tutorial/ +``` + +### Monitoring Deployments + +You can monitor deployment status through: + +- **GitHub Actions tab**: View workflow runs and their status +- **Environment tab**: Track deployments to the `github-pages` environment +- **Settings > Pages**: Verify GitHub Pages configuration +- **Repository insights**: View deployment frequency and success rates + +### Troubleshooting Workflow Issues + +Common issues and solutions: + +1. **Build Failures**: + - Check the workflow logs for Antora errors + - Verify `antora-assembler.yml` configuration + - Ensure all referenced content sources are accessible + +2. **Deployment Failures**: + - Verify GitHub Pages is enabled in repository settings + - Check that the workflow has necessary permissions + - Ensure the repository has GitHub Pages configured + +3. **Content Not Updating**: + - Check if the workflow completed successfully + - Verify the build generated the expected output + - Clear browser cache to see latest changes + +### Workflow Customization + +To customize the workflow for your needs: + +1. **Change trigger conditions**: Modify the `on:` section to change when the workflow runs +2. **Update Node.js version**: Change the Node.js version in the setup step +3. **Add build steps**: Include additional processing steps before or after Antora +4. **Configure notifications**: Add steps to notify team members of deployment status + +### Migration from Static Deployment + +Previously, the repository included a `static.yml` workflow that deployed raw repository content. This has been removed in favor of the Antora-based workflow because: + +- **Proper documentation processing**: Antora generates a structured documentation site +- **Better navigation**: Antora provides proper navigation and cross-references +- **Improved maintenance**: Single workflow eliminates deployment conflicts +- **Enhanced features**: Support for themes, search, and multi-version documentation + ## Future Improvements Consider these potential improvements to the documentation site: @@ -744,66 +891,4 @@ When troubleshooting UI problems: 1. Use browser developer tools to inspect elements and styles 2. Check the browser console for JavaScript errors 3. Verify that all required resources are loading correctly -4. Test with different browsers to identify browser-specific issues - -## GitHub Actions Workflow for Deployment - -The documentation site is automatically built and deployed using GitHub Actions. Below is an overview of the workflow: - -### Workflow Configuration - -The workflow is defined in `.github/workflows/antora.yml` and includes the following steps: - -1. **Checkout Repository**: - Uses the `actions/checkout@v3` action to fetch the repository. - -2. **Set up Node.js**: - Configures Node.js version `18` using `actions/setup-node@v3`. - -3. **Install Antora Locally**: - Installs Antora CLI and site generator locally: - ```bash - npm install @antora/cli @antora/site-generator-default - ``` - -4. **Verify Antora Installation**: - Ensures the required packages are installed: - ```bash - npm list @antora/cli @antora/site-generator-default || echo "Antora packages are not installed." - ``` - -5. **Generate Site with Antora**: - Builds the site using the playbook: - ```bash - npx antora --fetch --stacktrace playbook.yml - ``` - -6. **Setup Pages**: - Configures GitHub Pages using `actions/configure-pages@v4`. - -7. **Upload Site to GitHub Pages**: - Uploads the generated site artifact using `actions/upload-pages-artifact@v3`. - -8. **Deploy to GitHub Pages**: - Deploys the site using `actions/deploy-pages@v4`. - -### Permissions - -The workflow requires the following permissions: -- `id-token: write` for authentication. -- `contents: read` to access repository contents. -- `pages: write` to deploy the site to GitHub Pages. - -### Deployment URL - -After a successful deployment, the site is available at: -``` -https://.github.io// -``` -Replace `` (for e.g. microprofile) with your GitHub username and `` (for e.g. microprofile-tutorial) with the name of your repository. - -The production branch url for the MicroProfile Tutorial documentation would be: - -``` -https://microprofile.github.io/microprofile-tutorial/ -``` \ No newline at end of file +4. Test with different browsers to identify browser-specific issues \ No newline at end of file diff --git a/antora-assembler.yml b/antora-assembler.yml index 1fe8f5cb..1b8aace6 100644 --- a/antora-assembler.yml +++ b/antora-assembler.yml @@ -1,15 +1,15 @@ site: - title: MicroProfile Tutorial - url: https://microprofile.io - start_page: microprofile-tutorial::index.adoc + title: MicroProfile Tutorial # Overall site title + url: https://microprofile.io/tutorial # Base URL for the site + start_page: microprofile-tutorial::index.adoc # Homepage keys: - show_edit_page_link: true + show_edit_page_link: true # Enable "Edit this page" links content: sources: - - url: . - start_path: . - branches: HEAD + - url: "https://github.com/microprofile/microprofile-tutorial.git" # Current directory (local content) + branches: main # Use current branch + start_path: / # Root of the content ui: bundle: @@ -35,12 +35,12 @@ asciidoc: antora: extensions: - - require: '@antora/lunr-extension' + - require: '@antora/lunr-extension' # Search functionality index_latest_only: true - - require: '@antora/pdf-extension' - generate_index: true - index_filename: microprofile-tutorial - output_format: pdf + - require: '@antora/pdf-extension' # PDF generation + as_attachment: true + filename: microprofile-tutorial.pdf + output_dir: ./build/assembler output: dir: ./build/site \ No newline at end of file diff --git a/antora.yml b/antora.yml index 2a39e118..873446b0 100644 --- a/antora.yml +++ b/antora.yml @@ -1,12 +1,12 @@ -name: microprofile-tutorial -title: MicroProfile Tutorial -version: 6.1 -edit_url: https://github.com/microprofile/microprofile-tutorial/tree/main/modules/ROOT/pages/{path} -asciidoc: - attributes: +name: microprofile-tutorial # Component name/identifier +title: MicroProfile Tutorial # Display title for the component +version: 6.1 # Version of this component +edit_url: https://github.com/microprofile/microprofile-tutorial/tree/main/modules/ROOT/pages/{path} +asciidoc: # AsciiDoc processing settings + attributes: # Document attributes source-language: asciidoc@ table-caption: false xrefstyle: full -nav: - - modules/ROOT/pages/nav.adoc -start_page: index.adoc +nav: # Navigation menu definition + - modules/ROOT/pages/nav.adoc # Points to navigation file +start_page: index.adoc # Default landing page diff --git a/build/assembler/microprofile-tutorial/6.1/microprofile-tutorial.pdf b/build/assembler/microprofile-tutorial/6.1/microprofile-tutorial.pdf index 43e6202c..006883e8 100644 Binary files a/build/assembler/microprofile-tutorial/6.1/microprofile-tutorial.pdf and b/build/assembler/microprofile-tutorial/6.1/microprofile-tutorial.pdf differ diff --git a/build/site/404.html b/build/site/404.html index 3d406417..26166e1f 100644 --- a/build/site/404.html +++ b/build/site/404.html @@ -4,30 +4,54 @@ Page Not Found :: MicroProfile Tutorial - - - - - + + + + + + - + - + +
Edit this Page
- +
+
Edit this Page
+
diff --git a/build/site/microprofile-tutorial/6.1/chapter02/chapter02-00.html b/build/site/microprofile-tutorial/6.1/chapter02/chapter02-00.html index 10c15cdc..c3cac0e1 100644 --- a/build/site/microprofile-tutorial/6.1/chapter02/chapter02-00.html +++ b/build/site/microprofile-tutorial/6.1/chapter02/chapter02-00.html @@ -3,15 +3,38 @@ -Getting Started with MicroProfile :: MicroProfile Tutorial :: MicroProfile Tutorial +Getting Started with MicroProfile :: MicroProfile Tutorial :: MicroProfile Tutorial - + + + - - + - + +
-
Edit this Page
- +
Edit this Page
+