Advanced Antora

Slides used during an internal education about the Antora documentation generation system.

Transcript

1. VSHN – The DevOps Company Adrian Kosmaczewski Advanced Antora 1
2. VSHN – The DevOps Company Introduction to Antora Project organization: components and modules Content: code, diagrams, equations Antora at VSHN Links to more information Contents 2
3. VSHN – The DevOps Company  Full separation of content from "look & feel"  Created by the team What is Antora? The multi-repository documentation site generator for tech writers who  writing in AsciiDoc Asciidoctor 3
4. VSHN – The DevOps Company ROOT Module docs Documentation UI bundle (zip file) SDDs Module docs.syn.tools Steward Commodore antora ui default docs docs How does it work? 4
5. VSHN – The DevOps Company 1. The antora command reads a YAML le called the "playbook" 2. Clones the corresponding Git repositories Using 3. Uses to transform all les into HTML 4. Loads a UI bundle (zip le) 5. Builds a website ready to be used How does it work? isomorphic-git.org Asciidoctor 5
6. VSHN – The DevOps Company Antora is written in JavaScript (requires Node.js) nvm recommended: Using npm: Using yarn: Installation github.com/nvm-sh/nvm $ npm install --global @antora/cli@2.2 $ npm install --global @antora/site-generator-default@2.2 $ yarn global add @antora/cli@2.2 $ yarn global add @antora/site-generator-default@2.2 6
7. VSHN – The DevOps Company Usually three or more locations: 1. One or more documentation folders, located in their respective projects Let’s call those the "Components", like "Commodore" and "Steward" in Project Syn 2. One builder project Usually private, let’s call it the "Builder" 3. One UI bundle project Project Structure 7
8. VSHN – The DevOps Company 1 antora.yml le declaring an Antora component 2 The ROOT module is the default module 3 Contents of this le appear in the navigation bar component ├── LICENSE ├── README.adoc ├── docs │ ├── antora.yml │ └── modules │ └── ROOT │ ├── assets │ │ └── images │ │ ├── appuio.svg │ │ └── vshn.svg │ ├── nav.adoc │ └── pages │ ├── another.adoc │ └── index.adoc └── src └── code.py 1 2 3 8
9. VSHN – The DevOps Company For each location, 2 di erent YAML les: antora.yml For each component playbook.yml In the "Builder", containing all the metadata required to build the website, like the name, URL, location of the UI bundle, etc YAML Files 9
10. VSHN – The DevOps Company antora.yml name: secret title: Secret Python Project version: v1.0 start_page: ROOT:index.adoc nav: - modules/ROOT/nav.adoc 10
11. VSHN – The DevOps Company 1 What? 2 How? 3 Where? site: title: Secret Python Project url: https://secret-python-project.url/ start_page: secret::index.adoc content: sources: - url: https://gitlab.com/akosma/sample-antora-project.git start_path: docs ui: bundle: url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build output: destinations: - provider: fs 1 2 3 11
12. VSHN – The DevOps Company How to use $ antora playbook.yml $ antora --fetch playbook.yml $ antora --cache-dir=.cache/antora playbook.yml 12
13. Secret Python Project This is the documentation of the secret Python project. This project is sponsored by: This is a link to Module 2. Secret Python Project ROOT module Home Page Another Page Diagram with Kroki Math Equations Embedded Video Tables Other Components Module 2 Secret Python Project v2.1 Secret Python Project / ROOT module / Home Page Edit this Page Secret Python Project Home Products Services Resources Download VSHN – The DevOps Company 13
14. VSHN – The DevOps Company URLs {playbook.yml:site:url}/{antora.yml:name}/{antora.yml:version}/filename.html 14
15. VSHN – The DevOps Company  100% Asciidoctor Video Images Tables Source Code Diagrams Content 15
16. VSHN – The DevOps Company In the same module: To another component or module: Deep link: External: Links xref:page.adoc[Another page] xref:component:module:page.adoc[Another Page] xref:page.adoc#fragment[Link to anchor] https://other-website.com/page.html[Link] 16
17. VSHN – The DevOps Company Antora in VSHN handbook.vshn.ch kb.vshn.ch k8up.io docs.syn.tools vshn-oc-docs.appuioapp.ch 17
18. VSHN – The DevOps Company site: title: Secret Python Project url: https://secret-python-project.url/ start_page: secret::index.adoc robots: disallow keys: google_analytics: 'UA-54393406-6' content: sources: - url: https://gitlab.com/akosma/sample-antora-project.git branches: master # url: . # If the current folder is the repo to extract docs from # branches: HEAD # "HEAD" uses whichever branch is currently checked out tags: - v1.0 - v1.5 - v2.0 start_path: docs edit_url: 'https://gitlab.com/akosma/sample-antora-project/-/edit/master/{path}' - url: https://github.com/projectsyn/documentation.git branches: master start_path: docs edit_url: 'https://github.com/projectsyn/documentation/edit/master/{path}' - url: https://github.com/vshn/kb.git branches: master start_path: docs edit_url: 'https://github.com/vshn/kb/edit/develop/{path}' 18
19. VSHN – The DevOps Company  Antora does not provide any search capability For our websites, 2 additional steps during build: 1. to index website 2. in sidecar container in K8s deployment Search github.com/vshn/antora-indexer-cli github.com/vshn/embedded-search-engine 19
20. VSHN – The DevOps Company apiVersion: v1 kind: DeploymentConfig metadata: name: vshn-handbook labels: app: vshn-handbook spec: template: metadata: labels: app: vshn-handbook spec: containers: - name: vshn-handbook-main image: registry.svc/handbook/main:latest imagePullPolicy: Always ports: - name: http containerPort: 8080 protocol: TCP - name: vshn-handbook-search image: registry.svc/handbook/search:latest imagePullPolicy: Always ports: - name: http containerPort: 3000 protocol: TCP 1 2 20
21. VSHN – The DevOps Company 1 Redirecting searches to the other container server { listen 8080; server_name localhost; location / { root /usr/share/nginx/html; index index.html index.htm; } location /search { proxy_pass http://localhost:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_cache_bypass $http_upgrade; } } 1 21
22. VSHN – The DevOps Company Antora is a multi-repo doc site generator Strict folder structure Documentation projects consist of components Components are de ned with the antora.yml le Components consist of modules Modules have pages, images, etc… playbook.yml de nes the build process Conclusion 22
23. VSHN – The DevOps Company Documentation: Antora VSHN image: Search Engine: UI Bundles: Links docs.antora.org/antora/2.2 github.com/vshn/antora-docker github.com/vshn/antora-indexer-cli github.com/vshn/embedded-search-engine github.com/vshn/antora-ui-default github.com/projectsyn/antora-ui-default 23
24. VSHN – The DevOps Company Adrian Kosmaczewski – VSHN AG – Neugasse 10 – CH-8005 Zürich – +41 44 545 53 00 – – Ticket: Thanks! adrian@vshn.ch vshn.ch info@vshn.ch VINT-1716 24